Utwórz żądanie z POST, które zawiera kody odpowiedzi 200 lub 201 i zawartość

Przypuśćmy, że piszę usługę REST, której celem jest dodanie nowego elementu danych do systemu.

Planuję POST do

http://myhost/serviceX/someResources

Załóżmy, że to zadziała, jakiego kodu odpowiedzi powinienem użyć? I jaką treść mogę wrócić.

Patrzę na definicje kodów odpowiedzi HTTP i widzę te możliwości:

200: Zwróć jednostkę opisującą lub zawierającą wynik działania;

201: co oznacza STWORZONO. Znaczenie * Żądanie zostało spełnione i spowodowało utworzenie nowego zasobu. Do nowo utworzonego zasobu można się odwoływać za pomocą identyfikatorów URI zwróconych w jednostce odpowiedzi, z najbardziej szczegółowym identyfikatorem URI dla zasobu podanym w polu nagłówka lokalizacji. Odpowiedź POWINNA zawierać encję zawierającą listę charakterystyk zasobów i lokalizacji, z których użytkownik lub agent użytkownika może wybrać najbardziej odpowiednią. Format jednostki jest określony przez typ nośnika podany w polu nagłówka Content-Type. *

Ta ostatnia brzmi bardziej zgodnie ze specyfikacją HTTP, ale nie mam pojęcia, co

Odpowiedź POWINNA zawierać encję zawierającą listę charakterystyk zasobów i lokalizacji

znaczy.

Zalecenia? Interpretacje?

Chodzi o to, że treść odpowiedzi podaje stronę, która prowadzi do danej rzeczy:

201 Utworzono

Kod stanu 201 (Utworzono) wskazuje, że żądanie zostało spełnione i spowodowało utworzenie co najmniej jednego nowego zasobu. Podstawowy zasób utworzony przez żądanie jest identyfikowany przez pole nagłówka lokalizacji w odpowiedzi lub, jeśli nie otrzymano pola lokalizacji, przez efektywny identyfikator URI żądania.

Oznacza to, że Locationw nagłówku odpowiedzi umieścisz a, który zawiera adres URL miejsca, w którym możesz znaleźć nowo utworzoną rzecz :

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/36373586/12597

Treść odpowiedzi

Następnie wspominają, co należy zawrzeć w treści odpowiedzi :

Ładunek odpowiedzi 201 zwykle opisuje i łączy do utworzonych zasobów.

Człowiek korzystający z przeglądarki daje mu coś, na co może spojrzeć i kliknąć, aby dostać się do nowo utworzonego zasobu:

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/36373586/12597
Content-Type: text/html

Your answer has been saved! 
Click <A href="https://stackoverflow.com/a/36373586/12597">here</A> to view it.

Jeśli strona będzie używana tylko przez robota, sensowne jest, aby odpowiedź była czytelna dla komputera:

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/36373586/12597
Content-Type: application/xml

<createdResources>
   <questionID>1860645</questionID>
   <answerID>36373586</answerID>
   <primary>/a/36373586/12597</primary>
   <additional>
      <resource>http://stackoverflow.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content/36373586#36373586</resource>
      <resource>http://stackoverflow.com/a/1962757/12597</resource>
   </additional>
</createdResource>

Lub, jeśli wolisz:

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/36373586/12597
Content-Type: application/json

{ 
   "questionID": 1860645, 
   "answerID": 36373586,
   "primary": "/a/36373586/12597",
   "additional": [
      "http://stackoverflow.com/questions/1860645/create-request-with-post-which-response-codes-200-or-201-and-content/36373586#36373586",
      "http://stackoverflow.com/a/36373586/12597"
   ]
}

Odpowiedź zależy wyłącznie od Ciebie; to arbitralnie to, co chcesz.

Przyjazny dla pamięci podręcznej

Wreszcie jest optymalizacja, dzięki której mogę wstępnie buforować utworzony zasób (ponieważ mam już zawartość; właśnie ją przesłałem). Serwer może zwrócić datę lub ETag, które mogę przechowywać z treścią, którą właśnie załadowałem:

W sekcji 7.2 omówiono znaczenie i cel pól nagłówka walidatora, takich jak ETag i Last-Modified w odpowiedzi 201.

HTTP/1.1 201 Created
Date: Sat, 02 Apr 2016 12:22:40 GMT
Location: http://stackoverflow.com/a/23704283/12597
Content-Type: text/html
ETag: JF2CA53BOMQGU5LTOQQGC3RAMV4GC3LQNRSS4
Last-Modified: Sat, 02 Apr 2016 12:22:39 GMT 

Your answer has been saved! 
Click <A href="https://stackoverflow.com/a/36373586/12597">here</A> to view it.

A ETagsą to wartości czysto arbitralne. Ważne jest, aby były inne, gdy zmieniają się zasoby (i pamięci podręczne wymagają aktualizacji). ETag jest zwykle hashem (np. SHA2). Ale może to być baza danych rowversionlub rosnący numer wersji. Wszystko, co zmieni się, gdy coś się zmieni.

Myślę, że atompub REST API jest doskonałym przykładem uspokajającej usługi. Zobacz poniższy fragment ze specyfikacji atompub:

POST /edit/ HTTP/1.1
Host: example.org
User-Agent: Thingio/1.0
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Type: application/atom+xml;type=entry
Content-Length: nnn
Slug: First Post

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Atom-Powered Robots Run Amok</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2003-12-13T18:30:02Z</updated>
  <author><name>John Doe</name></author>
  <content>Some text.</content>
</entry>

Serwer sygnalizuje pomyślne utworzenie kodem stanu 201. Odpowiedź zawiera nagłówek lokalizacji wskazujący identyfikator URI elementu członkowskiego wpisu atomu oraz reprezentację tego wpisu w treści odpowiedzi.

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/edit/first-post.atom
ETag: "c180de84f991g8"  

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Atom-Powered Robots Run Amok</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2003-12-13T18:30:02Z</updated>
  <author><name>John Doe</name></author>
  <content>Some text.</content>
  <link rel="edit"
      href="http://example.org/edit/first-post.atom"/>
</entry>

Wpis utworzony i zwrócony przez kolekcję może nie odpowiadać wpisowi POST przesłanemu przez klienta. Serwer MOŻE zmienić wartości różnych elementów we wpisie, takich jak wartości atom: id, atom: updated i atom: author, i MOŻE zdecydować się na usunięcie lub dodanie innych elementów i atrybutów lub zmianę zawartości elementu i wartości atrybutów.

W kilku słowach:

• 200, gdy obiekt jest tworzony i zwracany
• 201 gdy obiekt jest tworzony, ale zwracane jest tylko jego odwołanie (takie jak identyfikator lub łącze)

Sprawdź HTTP: definicje metod: POST .

Akcja wykonana przez metodę POST może nie skutkować zasobem, który można zidentyfikować za pomocą identyfikatora URI. W tym przypadku odpowiedni stan odpowiedzi to 200 (OK) lub 204 (Brak treści), w zależności od tego, czy odpowiedź zawiera jednostkę opisującą wynik.

Jeśli zasób został utworzony na serwerze pochodzenia, odpowiedź POWINNA być 201 (utworzona) i zawierać jednostkę opisującą stan żądania i odwołującą się do nowego zasobu oraz nagłówek lokalizacji (patrz sekcja 14.30).

http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19

To tylko para klucz-wartość rozdzielana dwukropkami.

ETag: „xyzzy”

Mogą to być dane tekstowe dowolnego typu - generalnie dołączam ciąg JSON z identyfikatorem utworzonego elementu. Już sama łatwość testowania sprawia, że ​​warto to zrobić.

ETag: "{ id: 1234, uri: 'http://domain.com/comments/1234', type: 'comment' }"

W tym przykładzie identyfikator, uri i typ utworzonego elementu to „charakterystyka i lokalizacja zasobu”.

Dane wyjściowe są w rzeczywistości zależne od żądanego typu zawartości. Jednak przynajmniej powinieneś umieścić zasób, który został utworzony w lokalizacji. Podobnie jak wzorzec Post-Redirect-Get.

W moim przypadku zostawiam to pole puste, dopóki nie zażądam inaczej. Ponieważ takie jest zachowanie JAX-RS podczas używania Response.created ().

Pamiętaj jednak, że przeglądarki i frameworki, takie jak Angular, nie podążają automatycznie za wersjami 201. Zauważyłem zachowanie w http://www.trajano.net/2013/05/201-created-with-angular-resource/

Inną odpowiedzią, jaką miałbym na to, byłoby przyjęcie pragmatycznego podejścia i zachowanie kontraktu REST API uproszczenie . W moim przypadku zrefaktoryzowałem moje REST API, aby uczynić rzeczy bardziej testowalnymi bez uciekania się do JavaScript lub XHR, tylko proste formularze HTML i linki.

Aby być bardziej szczegółowym w powyższym pytaniu, użyłbym po prostu kodu zwrotnego 200 i otrzymam wiadomość w formacie JSON, którą aplikacja może zrozumieć. W zależności od potrzeb może wymagać identyfikatora nowo utworzonego obiektu, aby aplikacja internetowa mogła pobrać dane w innym wywołaniu.

Jedna uwaga, w mojej refaktoryzowanej umowie API odpowiedzi POST nie powinny zawierać żadnych danych, które można zapisać w pamięci podręcznej, ponieważ posty POST nie są tak naprawdę buforowalne, więc ogranicz je do identyfikatorów, które można żądać i buforować za pomocą żądania GET.