Jak zaprojektować prosty interfejs API CRUD REST

Question

Projektuję prosty interfejs API CRUD REST. To jest mój pierwszy raz, więc chciałem uzyskać informacje zwrotne na temat tego, czy mój projekt ma sens.

Używam metod HTTP: GET, POST, DELETE i UPDATE. Interfejs API pobierze i pobierze dane w formacie JSON. Próbka URL będzie taki jak ten:

GET (list): curl http://<domain>/myapp/rest/v1/colors 
POST: curl -XPOST http://<domain>/myapp/rest/v1/colors -d '{ 
     "name": "red", 
     "shade": "light" 
     }' 
GET (single item): curl http://<domain>/myapp/rest/v1/colors/2 
DELETE: curl -XDELETE http://<domain>/myapp/rest/v1/colors/2 
etc... 

Pytanie

Po żądania POST rekord zostanie utworzony w bazie danych. Zatem, czy żądanie POST powinno zwrócić identyfikator nowo utworzonego rekordu? Czy ten identyfikator może być użyty w UPDATE, DELETE and GET (single item)?

Answer 1

HTTP specification określa następujące POST:

Jeśli zasób została utworzona na serwerze pochodzenia, odpowiedź powinna być 201 (Utworzono) i zawierać podmiot, który opisuje status wniosku i odnosi do nowego zasobu oraz nagłówek Location (patrz: pkt 14.30).

Więc to w zasadzie oznacza:

• Należy zwrócić 201 Created jako kod statusu
• Należy zwrócić Location głową, wskazując na URI nowo utworzonego zasobu
• Można ewentualnie zawierać reprezentacja zasobu w treści odpowiedzi POST w celu zwolnienia klienta z konieczności wystawienia kolejnego żądania GET na wartość uzyskaną z nagłówka Location.

Answer 2

POST powinien zwrócić przekierowanie do nowego adresu URL dla pojedynczej pozycji.

Prawdopodobnie chcesz utracić identyfikator wersji adresów URL.

Zamiast tego zaprojektuj swoje reprezentacje i klientów w taki sposób, aby z wdziękiem obsługiwać różne wersje. Na przykład klient nie powinien polegać na określonym formacie, ale tylko na atrybutach, których potrzebuje.

To, czego brakuje w twoim opisie, to zasada HATEOAS, to znaczy, że klient nie powinien twardo kodować żadnych adresów URL, ale znajdować adresy URL dla dalszych działań wewnątrz reprezentacji innych podmiotów. Ponieważ nie wyświetlasz przykładowego dokumentu dla wyników zwróconych przez adresy URL, nie możemy powiedzieć, czy zrobiłeś to w miły sposób.

Zapoznaj się z this presentation, wyjaśnia temat, a także wspomina o Bibliotece Wiosennej przydatnej do jej realizacji.