API RESTful. Dovrei restituire l'oggetto che è stato creato / aggiornato?

25

Sto progettando un servizio web RESTful usando WebApi e mi chiedevo quali risposte HTTP e corpi di risposta dovessero ritornare durante l'aggiornamento / creazione di oggetti.

Ad esempio, posso utilizzare il metodo POST per inviare alcuni JSON al servizio Web e quindi creare un oggetto. È consigliabile impostare lo stato HTTP su creato (201) o ok (200) e semplicemente restituire un messaggio come "Nuovo impiegato aggiunto" o restituire l'oggetto che è stato originariamente inviato?

Lo stesso vale per il metodo PUT. Quale stato HTTP è il migliore da usare e devo restituire l'oggetto che è stato creato o solo un messaggio? Considerando il fatto che l'utente sa quale oggetto stanno cercando di creare / aggiornare comunque.

Qualche idea?

Esempio:

Aggiungi nuovo impiegato:

POST /api/employee HTTP/1.1
Host: localhost:8000
Content-Type: application/json

{
    "Employee": {
        "Name" : "Joe Bloggs",
        "Department" : "Finance"
    }
}

Aggiorna dipendente esistente:

PUT /api/employee HTTP/1.1
Host: localhost:8000
Content-Type: application/json

{
    "Employee": {
        "Id" : 1
        "Name" : "Joe Bloggs",
        "Department" : "IT"
    }
}

Risposte:

Risposta con oggetto creato / aggiornato

HTTP/1.1 201 Created
Content-Length: 39
Content-Type: application/json; charset=utf-8
Date: Mon, 28 Mar 2016 14:32:39 GMT

{
    "Employee": {
        "Id" : 1
        "Name" : "Joe Bloggs",
        "Department" : "IT"
    }
}

Risposta con solo messaggio:

HTTP/1.1 200 OK
Content-Length: 39
Content-Type: application/json; charset=utf-8
Date: Mon, 28 Mar 2016 14:32:39 GMT

{
    "Message": "Employee updated"
}

Risposta con solo codice di stato:

HTTP/1.1 204 No Content
Content-Length: 39
Date: Mon, 28 Mar 2016 14:32:39 GMT
    
posta iswinky 28.03.2016 - 16:53
fonte

4 risposte

23

Come molte cose, dipende. Il compromesso è la facilità d'uso rispetto alle dimensioni della rete. Può essere molto utile per i clienti vedere la risorsa creata. Può includere campi compilati dal server, come ad esempio l'ultima creazione. Poiché sembra che tu stia includendo id invece di utilizzare hateoas , i clienti probabilmente vorranno vedere l'id per la risorsa che hanno appena POST ed.

Se non si include la risorsa creata, si prega di non creare un messaggio arbitrario. I campi 2xx e Location sono informazioni sufficienti per garantire ai clienti che la loro richiesta sia stata gestita correttamente.

    
risposta data 28.03.2016 - 17:16
fonte
9

@iswinky Vorrei sempre rimandare il carico utile in caso di POST e PUT.

In caso di POST potresti creare l'entità con un ID interno o un UUID. Quindi ha senso restituire il carico utile.

Analogamente, nel caso di PUT, potresti ignorare alcuni campi dell'utente (valori immutabili, ad esempio), o nel caso di un PATCH, i dati potrebbero essere stati modificati anche da altri utenti.

L'invio dei dati così come è stato effettuato è sempre una buona idea e sicuramente non danneggia. Se il chiamante non ha bisogno di questi dati restituiti, non li elaborerà ma utilizzerà semplicemente lo statusCode. Altrimenti possono usare questi dati come qualcosa per aggiornare l'interfaccia utente con.

È solo in caso di DELETE che non restituirei il carico utile e farei un 200 con un contenuto di risposta, o un 204 senza contenuto di risposta.

    
risposta data 28.03.2016 - 17:14
fonte
9

Personalmente, I sempre restituisce solo 200 OK .

Per citare la tua domanda

Considering the fact that the user knows what object they are trying to create / update anyway.

Perché aggiungere ulteriore larghezza di banda (che potrebbe dover essere pagata) per dire al cliente ciò che già sa?

    
risposta data 29.03.2016 - 12:39
fonte
3

Facendo riferimento al link standard RFC , dovresti restituire lo stato 201 (creato) alla memorizzazione corretta del richiedere la risorsa usando Post. Nella maggior parte delle applicazioni l'id della risorsa viene generato dal server stesso, quindi è buona pratica restituire l'id della risorsa creata. Restituire l'intero oggetto è il sovraccarico per la richiesta di posta. La pratica ideale è di restituire la posizione dell'URL della risorsa appena creata.

Ad esempio, è possibile fare riferimento al seguente esempio che salva l'oggetto Employee nel database e restituisce l'URL dell'oggetto risorsa appena creato come risposta.

@RequestMapping(path = "/employees", method = RequestMethod.POST)
public ResponseEntity<Object> saveEmployee(@RequestBody Employee employee) {
        int id = employeeService.saveEmployee(employee);
        URI uri = ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(id).toUri();
        return ResponseEntity.created(uri).build();
}

Questo endpoint di riposo restituirà la risposta come:

Stato 201 - CREATO

Posizione dell'intestazione → link

    
risposta data 23.10.2018 - 08:39
fonte

Leggi altre domande sui tag