Un endpoint POST in un'API REST consente l'inclusione di risorse correlate?

Question

Un endpoint POST in un'API REST consente l'inclusione di risorse correlate?

#1 da (2 voti)
#2 da (1 voti)

2

Considerati i seguenti endpoint REST:

(GET, POST)  /api/v2/employer
(GET)        /api/v2/employer/{id}
(GET, POST)  /api/v2/employer/{id}/employees

Un consumatore di questa API ha la possibilità di pubblicare una nuova risorsa del datore di lavoro che include un elenco di dipendenti? Ad esempio:

POST: /api/v2/employer

{
    employerName: "Bob's Plumbing",
    headquarters: "Des Moines, IA, US",
    industry: "plumbing",
    employees: [
        { firstName: "Bob", lastName: "Jones", dob: "1982-05-16" },
        { firstName: "Philip", lastName: "Jones", dob: "2001-03-12" },
        { firstName: "John", lastName: "Smith", dob: "1991-02-19" }
    ]
}

O , dovrebbe essere richiesto al consumatore di suddividerlo in più chiamate?

POST: /api/v2/employer

{
    employerName: "Bob's Plumbing",
    headquarters: "Des Moines, IA, US",
    industry: "plumbing",
}

// ... the ID of the new employer is returned (for example, "5") ...

POST: /api/v2/employer/5/employees

{ firstName: "Bob", lastName: "Jones", dob: "1982-05-16" }

POST: /api/v2/employer/5/employees

{ firstName: "Philip", lastName: "Jones", dob: "2001-03-12" }

POST: /api/v2/employer/5/employees

{ firstName: "John", lastName: "Smith", dob: "1991-02-19" }

api-design architecture api rest web-api

posta Nathan Friend 08.06.2018 - 14:33

fonte

2 risposte

Leggi altre domande sui tag api-design architecture api rest web-api

Prenotazione dell'indipendenza del database utilizzando Spring JPA Esiste un modello per descrivere una classe che simboleggia un'istanza di un'istanza di un'altra classe?

score 2 · Answer 1

Should a consumer of this API have the ability to POST a new employer resource that includes a list of employees?

Euristica: immagina la tua API come un mucchio di pagine web.

È ragionevole disporre di un modulo in cui un consumatore aggiunge voci a un elenco di dipendenti e quindi invia tale modulo in una singola richiesta?

Non conosco i dettagli del tuo caso d'uso, quindi non posso dirlo con certezza. Ma posso offrire i seguenti suggerimenti

Il fatto che si utilizzino convenzioni di ortografia URI che rendano più semplice per gli esseri umani la comprensione della semantica dell'identificatore non ha importanza .
Il fatto che il corpo del messaggio della richiesta sia una rappresentazione application / json dei dati, piuttosto che una rappresentazione application / x-www-form-urlencoded non ha importanza .
In HTTP, la selezione dell'URI di destinazione per un POST è più su quale risorsa si desidera che il client sfrutti dalla sua cache piuttosto che su come il server sta organizzando i suoi dati privati.

score 1 · Answer 2

Dipende da come sono organizzati i tuoi aggregati. Nel tuo esempio sopra, Employer è un aggregato. Se stai modificando l'elenco dei dipendenti preesistenti che appartengono al datore di lavoro, questo dovrebbe essere mantenuto con l'aggiornamento del datore di lavoro. ad esempio, l'elenco degli ID dei dipendenti deve essere incluso nel Datore di lavoro JSON e mantenuto come necessario.

Non dovresti creare nuovi dipendenti in questo modo. Nella maggior parte dei sistemi, Employee sarebbe un aggregato separato, quindi presumo che sia vero anche qui. In tal caso, probabilmente hai un endpoint per Dipendente e nuovi dipendenti dovrebbero essere creati / aggiornati lì.

Se hai creato i Dipendenti come parte dell'aggiornamento del Datore di lavoro, essi vengono trattati come entità, non come aggregati completi e quindi vengono convalidati nel contesto di un Datore di lavoro. Se si dispone di regole aziendali che impongono a un Dipendente di disporre di un indirizzo postale, questa regola potrebbe non essere applicata nel contesto di un Datore di lavoro, ma verrà applicata quando si salva il Dipendente da solo. Potresti pensare che puoi solo convalidare anche i dipendenti, ma convalidare gli oggetti posseduti dal datore di lavoro significa che devi convalidare gli oggetti di cui è titolare il dipendente, il che significa che devi convalidare gli oggetti che possiedono, ecc.

BTW, il tuo esempio mostra i due estremi delle chiamate API, uno solo o molti. Se si utilizza l'endpoint Employee come descritto sopra, insieme alle idee di creazione multipla qui espresse:

link

Puoi mantenere le tue chiamate API fino a un massimo di 2.