PUT

Metoda PUT żąda utworzenia lub zastąpienia stanu zasobu docelowego stanem zdefiniowanym przez reprezentację zawartą w ładunku komunikatu żądania. Pomyślny PUT danej reprezentacji sugerowałby, że kolejny GET na tym samym zasobie docelowym spowoduje wysłanie równoważnej reprezentacji w odpowiedzi 200 (OK). Nie ma jednak gwarancji, że taka zmiana stanu będzie możliwa do zaobserwowania, ponieważ zasób docelowy może być równolegle obsługiwany przez innych agentów użytkownika lub może podlegać dynamicznemu przetwarzaniu przez serwer źródłowy, zanim jakikolwiek kolejny GET zostanie odebrany. Pomyślna odpowiedź oznacza jedynie, że intencja agenta użytkownika została osiągnięta w momencie jej przetwarzania przez serwer źródłowy.

Jeśli zasób docelowy nie ma aktualnej reprezentacji, a PUT pomyślnie ją utworzy, serwer źródłowy MUSI poinformować agenta użytkownika, wysyłając odpowiedź 201 (Utworzono). Jeśli zasób docelowy ma aktualną reprezentację i reprezentacja ta zostanie pomyślnie zmodyfikowana zgodnie ze stanem załączonej reprezentacji, serwer źródłowy MUSI wysłać odpowiedź 200 (OK) lub 204 (Brak zawartości), aby wskazać pomyślne zakończenie żądania.

Serwer źródłowy POWINIEN ignorować nierozpoznane pola nagłówka otrzymane w żądaniu PUT (tj, nie zapisywać ich jako części stanu zasobu).

Serwer źródłowy POWINIEN zweryfikować, czy reprezentacja PUT jest zgodna z wszelkimi ograniczeniami serwera dla zasobu docelowego, które nie mogą lub nie zostaną zmienione przez PUT. Jest to szczególnie ważne, gdy serwer źródłowy używa wewnętrznych informacji konfiguracyjnych związanych z URI w celu ustawienia wartości metadanych reprezentacji w odpowiedziach GET. Gdy reprezentacja PUT jest niezgodna z zasobem docelowym, serwer źródłowy POWINIEN albo zapewnić ich spójność, przekształcając reprezentację lub zmieniając konfigurację zasobu, albo odpowiedzieć odpowiednim komunikatem o błędzie zawierającym wystarczające informacje, aby wyjaśnić, dlaczego reprezentacja jest nieodpowiednia. Sugerowane są kody stanu 409 (Konflikt) lub 415 (Nieobsługiwany typ mediów), przy czym ten ostatni jest specyficzny dla ograniczeń dotyczących wartości Content-Type.

Na przykład, jeśli zasób docelowy jest skonfigurowany tak, aby zawsze miał Content-Type "text/html", a reprezentacja PUT ma Content-Type "image/jpeg", serwer źródłowy powinien wykonać jedną z następujących czynności:

• a. przekonfigurować zasób docelowy, aby odzwierciedlał nowy typ nośnika;
• b. przekształcić reprezentację PUT do formatu zgodnego z formatem zasobu przed zapisaniem go jako nowego stanu zasobu; lub,
• c. odrzucić żądanie z odpowiedzią 415 (Unsupported Media Type) wskazującą, że zasób docelowy jest ograniczony do "text/html", być może zawierającą link do innego zasobu, który byłby odpowiednim celem dla nowej reprezentacji.

HTTP nie definiuje dokładnie, w jaki sposób metoda PUT wpływa na stan serwera źródłowego poza tym, co może być wyrażone przez intencję żądania agenta użytkownika i semantykę odpowiedzi serwera źródłowego. Nie definiuje, czym może być zasób, w jakimkolwiek znaczeniu tego słowa, poza interfejsem dostarczanym przez HTTP. Nie definiuje, w jaki sposób stan zasobu jest "przechowywany", ani w jaki sposób takie przechowywanie może ulec zmianie w wyniku zmiany stanu zasobu, ani w jaki sposób serwer źródłowy tłumaczy stan zasobu na reprezentacje. Ogólnie rzecz biorąc, wszystkie szczegóły implementacji za interfejsem zasobu są celowo ukryte przez serwer.

Serwer źródłowy NIE MOŻE wysyłać pola nagłówka walidatora (sekcja 7.2), takiego jak pole ETag lub Last-Modified, w udanej odpowiedzi na PUT, chyba że dane reprezentacji żądania zostały zapisane bez żadnej transformacji zastosowanej do treści (tj. nowe dane reprezentacji zasobu są identyczne z danymi reprezentacji otrzymanymi w żądaniu PUT), a wartość pola walidatora odzwierciedla nową reprezentację. Ten wymóg pozwala agentowi użytkownika wiedzieć, kiedy ciało reprezentacji, które ma w pamięci, pozostaje aktualne w wyniku PUT, a zatem nie musi być ponownie pobierane z serwera źródłowego, a nowy walidator (y) otrzymany w odpowiedzi może być użyty do przyszłych żądań warunkowych, aby zapobiec przypadkowemu nadpisaniu (sekcja 5.2).

Zasadnicza różnica między metodami POST i PUT jest podkreślona przez różne intencje dla załączonej reprezentacji. Zasób docelowy w żądaniu POST ma obsługiwać załączoną reprezentację zgodnie z własną semantyką zasobu, podczas gdy załączona reprezentacja w żądaniu PUT jest zdefiniowana jako zastępująca stan zasobu docelowego. W związku z tym intencja PUT jest idempotentna i widoczna dla pośredników, nawet jeśli dokładny efekt jest znany tylko przez serwer źródłowy.

Właściwa interpretacja żądania PUT zakłada, że agent użytkownika wie, który zasób docelowy jest pożądany. Usługa, która wybiera odpowiedni URI w imieniu klienta, po otrzymaniu żądania zmiany stanu, POWINNA być zaimplementowana przy użyciu metody POST, a nie PUT. Jeśli serwer źródłowy nie dokona żądanej zmiany stanu PUT do zasobu docelowego i zamiast tego chce, aby została ona zastosowana do innego zasobu, na przykład gdy zasób został przeniesiony do innego URI, wówczas serwer źródłowy MUSI wysłać odpowiednią odpowiedź 3xx (Przekierowanie); agent użytkownika MOŻE następnie podjąć własną decyzję dotyczącą przekierowania żądania.

Żądanie PUT zastosowane do zasobu docelowego może mieć skutki uboczne dla innych zasobów. Na przykład, artykuł może mieć URI identyfikujący "aktualną wersję" (zasób), który jest oddzielny od URI identyfikujących poszczególne wersje (różne zasoby, które w pewnym momencie współdzieliły ten sam stan co zasób aktualnej wersji). Pomyślne żądanie PUT na URI "bieżącej wersji" może zatem utworzyć nowy zasób wersji oprócz zmiany stanu zasobu docelowego, a także może spowodować dodanie linków między powiązanymi zasobami.

Serwer źródłowy, który zezwala na PUT na danym zasobie docelowym, MUSI wysłać odpowiedź 400 (Bad Request) na żądanie PUT, które zawiera pole nagłówka Content-Range (sekcja 4.2 [RFC7233]), ponieważ ładunek jest prawdopodobnie częściową zawartością, która została omyłkowo PUT jako pełna reprezentacja. Częściowe aktualizacje zawartości są możliwe poprzez kierowanie oddzielnie zidentyfikowanego zasobu ze stanem, który pokrywa się z częścią większego zasobu, lub poprzez użycie innej metody, która została specjalnie zdefiniowana dla częściowych aktualizacji (na przykład metoda PATCH zdefiniowana w [RFC5789]).

Odpowiedzi na metodę PUT nie są buforowane. Jeśli pomyślne żądanie PUT przejdzie przez pamięć podręczną, która ma jedną lub więcej przechowywanych odpowiedzi dla efektywnego URI żądania, te przechowywane odpowiedzi zostaną unieważnione (patrz sekcja 4.4 [RFC7234]).

.