Rest API Design - Funziona con ID o stringhe letterali?

Let's say I have an Employee resource, which has a status and gender attributes. In the database Status and Gender and separate tables and thus separate Domain object, each with its own identifier.

Le rappresentazioni API non devono essere strettamente associate ai dettagli dell'implementazione. Direi che ricavare le rappresentazioni API dai dettagli dell'implementazione è esattamente al contrario.

Pensa a Adapter Pattern dal libro Gang of Four . I messaggi del web sono quelli di un negozio di documenti. Il tuo obiettivo nella creazione di un'API è produrre i documenti che i tuoi consumatori desiderano, isolandoli dai dettagli nitidi di produzione di tali documenti.

La motivazione per farlo è che puoi cambiare i dettagli di implementazione ogni volta che vuoi, con la certezza che - finché non cambierai le rappresentazioni che torni, i tuoi clienti non si romperanno.

Inoltre, tieni presente che una singola risorsa logica potrebbe avere molte rappresentazioni, solo alcune delle quali supportano la modifica.

let's say the client is updating the user

In quanto consumatore, con quale rappresentazione vuoi lavorare? La mia ipotesi è che il più vicino è

{
    "firstName": "Jane",
    "lastName": "Doe",
    "active": true,
    "gender": "FEMALE",
    "status": "FULL_TIME"
}

Se Metto questa rappresentazione in una posizione che specifichi, dovresti essere in grado di capire il resto.

Se stavi creando rappresentazioni per le macchine da utilizzare, probabilmente dovresti volere meno ambiguità nell'ortografia

{
    "https://schema.org/givenName": "Jane",
    "https://schema.org/familyName": "Doe",
    "active": true,
    "https://schema.org/gender": "https://schema.org/Female",
    "https://schema.org/employmentType": "FULL_TIME"
}

Stessa risorsa logica, due diverse rappresentazioni. Cavalli per i corsi.

Sia il caso 1 che il caso 2 hanno un bell'aspetto. La scelta può essere prevista dal modo in cui organizzi il tuo modello di dominio.

Hai rispecchiato le tabelle Employee, Gender e Status nel dominio (usando ORM suppongo). Ciascuna di queste classi in questo particolare modello è una entità che ha proprio identificativo . L'ulteriore esposizione dell'intero modello tramite API REST sembra logica e adatta al caso 1.

In alternativa, puoi attenersi ai principi DDD che prestano molta attenzione alle differenze tra entità e oggetti valore . Da questo punto di vista, Employee è un'entità (con id) e Gender e Status potrebbero essere buoni candidati per diventare value objects (incorporato nell'entità Employee, senza identificatori). Questo si adatta al caso 2.

Pienamente d'accordo con te sul fatto che Case 3 è un no.

Il caso 2 è l'unica opzione reale. Hai già indicato i problemi relativi al caso 3. Il caso 1 fornisce informazioni a cui il client dell'API non interessa (gli ID interni per gli stati, ad esempio) e richiede al cliente di sapere su chi costruire una richiesta PUT . Sì, la richiesta PUT è un po 'più concisa se può utilizzare gli ID invece delle stringhe complete, ma specificare "FULL_TIME" o "PART_TIME" è ciò che sa il client, non che capita di avere alcuni ID arbitrari nel database .

Naturalmente, puoi documentare gli ID nella documentazione della tua API, ma è altrettanto facile documentare i valori validi che le stringhe possono essere e, probabilmente, più chiari.

I dati enumerati come quelli che hai qui sono altamente memorizzabili nella cache. Usa link invece di oggetti. Utilizza le intestazioni di cache per consentire ai client di memorizzare nella cache i generi e gli stati localmente, diciamo per 24 ore. Quindi solo la prima chiamata del giorno lascia la macchina client. Probabilmente puoi anche configurare la memorizzazione nella cache per consentire ai server intermedi di conservare le informazioni, quindi alcune richieste dei client non arrivano nemmeno sul tuo server.

GET /employees/1
{
    "id": 1,
    "firstName": "Jane",
    "lastName": "Doe",
    "active": true,
    "gender": "/genders/1",
    "status": "/statuses/3"
}

// clients populate their dropdown with
GET /genders
[
    {"id":1, "gender":"FEMALE"},
    {"id":2, "gender":"MALE"},
    ...
]

// clients look up an employee's gender with
GET /genders/1
{
    "id": 1,
    "gender": FEMALE
}

Uno svantaggio è che /genders/1 non è leggibile dall'uomo. Puoi invece utilizzare /genders/female , ma non puoi mai cambiare il nome di un sesso senza rompere i client. Questa è la chiave sintetica rispetto al compromesso tra le chiavi naturali: flessibilità rispetto alla leggibilità umana.

Potresti anche prendere in considerazione la possibilità di inserire tutti i tuoi elenchi di valori in un unico endpoint comune, come

/lists/genders/1
/lists/statuses/3

Questo chiarirà ai clienti che sono tutte coppie di valori-chiave che appartengono a diversi raggruppamenti.

Mi piacerebbe fare qualcosa tra 1 e 2, per i motivi che David ha menzionato:

Non vuoi esporre l'ID delle cose se non necessario.

Tuttavia, l'esposizione dell'ID potrebbe diventare necessaria a un certo punto nel tempo. Se ciò accade, la retrocompatibilità è una preoccupazione. Quindi, vorrei fare questo:

{
    "id": 1,
    "firstName": "Jane",
    "lastName": "Doe",
    "active": true,
    "gender": {
        "name": "FEMALE"
    },
    "status": {
        "name": "FULL_TIME"
    }
}

Ha le stesse proprietà dell'opzione 2; ma ha il vantaggio che l'aggiunta dell'ID in seguito non introduce un'interruzione BC:

{
    "id": 1,
    "firstName": "Jane",
    "lastName": "Doe",
    "active": true,
    "gender": {
        "id": 1,
        "name": "FEMALE"
    },
    "status": {
        "id": 3,
        "name": "FULL_TIME"
    }
}

Come sottolinea Eric nei commenti, questo usa ancora il nome dell'entità come identificatore di uniqe. Se l'ID viene introdotto in un secondo momento, il nome deve rimanere invariato, perché i client più vecchi potrebbero (o meglio lo saranno ) avere codificato per questo.