Handling differenza RESTful struttura di rappresentanza tra POST e GET

Question

Sto progettando un'API REST e nonostante la pesca a strascico una serie di guide pratiche non riesco a trovare molto relativa al migliori pratiche di gestire la disparità tra struttura di rappresentanza necessario per un POST rispetto alla stessa struttura di rappresentazione restituita da un GET.

GET per un manichino user rappresentazione potrebbe essere simile a questo:

{ 
    "id": 1234, 
    "created": "2012-04-23T18:25:43.511Z", 
    "username": "johndoe@example.com", 
    "name": "John Doe" 
} 

Tuttavia, POST per lo stesso manichino user rappresentazione non può specificare alcune proprietà (vale a dire il id e created):

{ 
    "username": "johndoe@example.com", 
    "name": "John Doe" 
} 

Ovviamente questo è un esempio troppo semplificato ma dato che l'utente non può specificare determinati campi (e non potrebbe sempre s ovvio quali sono pertinenti al metodo applicato) è best practice per creare rappresentazioni separate per ciascuna o aspettarsi la versione più completa e gestire la disparità dei dati in modo trasparente sul server?

Nonostante l'apparente facilità di avere una singola rappresentazione e gestire il lato server di disparità, temo che questa sarebbe una brutta esperienza per un utente se non fosse chiaro quali valori possono essere specificati (o modificati usando PUT per esempio). Se la tendenza è quella di creare rappresentazioni separate c'è una convenzione di denominazione da applicare alla definizione della rappresentazione?

ad es. i_user per l'utente in entrata e o_user per l'utente in uscita. O user_full e user_min o user e .user ecc

Aggiornamento: Il mio esempio eccessivamente semplificato forse non illustrano adeguatamente la questione. Immagina una rappresentazione che abbia 50 proprietà (ad esempio una rappresentazione server con tutti i suoi attributi di monitoraggio - cpu, ram, temp, storage_drive_a, storage_drive_b, file_permission ecc.) Di queste 50 proprietà, 30 sono proprietà di sola lettura e 20 di queste sono valori che può essere impostato.

Answer 1

Prima di tutto, la semantica finali del metodo di POST sono determinati dalla risorsa mirata, non dal protocollo HTTP, come con gli altri metodi, in modo che il metodo di POST può fare tutto quello che vuoi, a patto che si documento correttamente, e non stai replicando funzionalità già standardizzate con altri metodi.

Quindi, in breve, non c'è niente di sbagliato nell'avere una rappresentazione diversa per il metodo POST e GET.

Tuttavia, chiedere una best practice in questo caso è inutile, perché ciò che definisce il formato di rappresentazione è il tipo di supporto utilizzato, non il metodo, ma la maggior parte delle cosiddette API REST su Internet utilizzano generico i tipi di media per tutto e i client si basano sulla semantica URI per sapere quale risorsa hanno a che fare, che non è affatto RESTful. Fondamentalmente, stai chiedendo le migliori pratiche per un problema che non esiste realmente in REST quando le cose sono fatte correttamente.

Quindi, per rispondere alla tua domanda, si può avere diverse rappresentazioni con diversi tipo di media - come la vostra rappresentazione completa dell'utente potrebbero avere un supporto di tipo application/vnd.mycompany.user.full.v1+json, e una rappresentazione utente semplificata potrebbe avere un supporto di tipo application/vnd.mycompany.user.min.v1+json - oppure è possibile avere una singola rappresentazione come application/vnd.mycompany.user.v1+json e la documentazione per questo tipo di supporto potrebbe descrivere in dettaglio come alcune proprietà potrebbero esistere o meno, o potrebbero avere valori predefiniti se non forniti. Il metodo POST richiederà un tipo di supporto per funzionare e risponderà con 415 Unsupported Media Type se i client inviano qualcos'altro nell'intestazione Content-Type. Allo stesso modo, un cliente può scegliere la rappresentazione desiderata con l'intestazione Accept.

Come puoi vedere, ciò che stai chiedendo non è un problema quando stai davvero facendo REST, e non semplicemente usandolo come buzzword per un'API HTTP.