W dobrze zaprojektowanym REST, PUT i PATCH to dwie metody HTTP służące do aktualizacji zasobów na serwerze, ale różnica między PUT a PATCH w REST API polega na sposobie wykonania aktualizacji i scenariuszach, w których każda z nich się sprawdza. Obie metody są przeznaczone do modyfikacji istniejących danych, ale zrozumienie różnicy między PUT a PATCH w REST API pomaga deweloperom wybrać najlepszą opcję w zależności od rodzaju aktualizacji. W tym artykule omówimy różnice między PUT a PATCH w REST API, skupiając się na dyskusji PATCH vs aktualizacja REST, kiedy używać każdej metody i jak wybrać właściwy sposób dla różnych przypadków użycia.
Czym jest PUT w REST API?
Żeby zrozumieć różnicę między PUT a PATCH w REST API, najpierw trzeba wiedzieć, czym jest PUT. Zgodnie z Sekcja 9.6 RFC 2616, metoda PUT w REST API żąda przechowywania przesłanej jednostki pod podanym adresem Request-URI.
Jeśli Request-URI wskazuje na już istniejący zasób, przesłana jednostka powinna być traktowana jako zmodyfikowana wersja zasobu na serwerze źródłowym. Jeśli Request-URI nie wskazuje na istniejący zasób i aplikacja kliencka może go utworzyć, serwer może go na tym adresie założyć.
Innymi słowy, metoda PUT służy do aktualizacji całego zasobu na serwerze. Stanowi to pełną aktualizację, używaną zwykle gdy trzeba całkowicie zastąpić zasób.
PUT sprawdza się najlepiej w takich przypadkach:
- Aktualizacja całego zasobu (np. profil użytkownika ze wszystkimi nowymi danymi).
- Zamiana całego elementu lub rekordu.
- Gdy tożsamość zasobu jest jasna i jego dane wymagają całkowitego odświeżenia.
W systemach takich jak Elasticsearch, operacje idempotentne gwarantują spójność danych. Na przykład aktualizacja dokumentu w Elasticsearch przy użyciu PUT zapewnia, że to samo żądanie można powtórzyć bez niezamierzonych efektów ubocznych.
Czym jest PATCH w REST API?
Skoro omówiliśmy PUT w REST API, spójrzmy na PATCH w REST API i jak działa, zanim porównamy PUT z PATCH w REST API. Zgodnie z RFC 5789, metoda PATCH w REST API żąda zastosowania zestawu zmian opisanych w żądaniu do zasobu określonego przez Request-URI.
To potwierdza różnicę PUT vs PATCH w REST API: wysyłasz tylko dane do modyfikacji, a serwer stosuje zmiany do istniejącego zasobu bez zmiany całości. Deweloperzy tworzą patche reprezentujące te przyrostowe zmiany, minimalizując transfer danych i optymalizując aktualizacje.
Dlatego metoda PATCH w REST API sprawdza się lepiej w następujących przypadkach:
- Aktualizacja tylko wybranych pól zasobu (na przykład zmiana adresu e-mail lub numeru telefonu użytkownika). Przykład PATCH API mógłby polegać na wysłaniu tylko nowego adresu e-mail, pozostawiając pozostałe pola bez zmian.
- Poprawa wydajności poprzez zmniejszenie rozmiaru przesyłanych danych.
- Gdy chcesz aktualizować zasób stopniowo zamiast go całkowicie zastępować.
- Twórz patche, które enkapsulują konkretne zmiany pól, na przykład modyfikację adresu e-mail użytkownika, bez wpływu na pozostałe dane.
Na platformach takich jak bezgłowy CMS które często obsługują złożone struktury treści, użycie PATCH do mniejszych aktualizacji (na przykład modyfikacja pojedynczego pola) może zmniejszyć obciążenie serwera i poprawić wydajność.
Po omówieniu tych dwóch metod powinieneś mieć wyobrażenie, czym są PUT i PATCH w REST APIs. Zanim jednak przejdziemy do różnic między PUT a PATCH w REST APIs, musimy poruszyć temat idempotencji w obu metodach.
Idempotentność w PUT vs PATCH w REST API
W REST APIs idempotencja odnosi się do właściwości operacji, która przy wielokrotnym powtórzeniu z tymi samymi danymi wejściowymi daje ten sam wynik. Oznacza to, że wysłanie tego samego żądania wiele razy powinno mieć taki sam wpływ na serwer, niezależnie od liczby wykonań. Jest to ważne dla zapewnienia stabilności i przewidywalności API. Ale na czym polega związek idempotencji z różnicą między PUT a PATCH w REST API?
Metoda PUT i idempotentność
Metoda PUT w REST API jest zawsze idempotentna, ponieważ została zaprojektowana do zastępowania całego zasobu pod określonym URI danymi zawartymi w żądaniu. Innymi słowy, jeśli wykonasz żądanie PUT wiele razy z tymi samymi danymi zasobu, wynik będzie zawsze taki sam.
Dlaczego PUT jest idempotentny? Gdy wysyłasz żądanie PUT, zasadniczo mówisz serwerowi: "To jest dokładny i pełny stan, jaki chcę dla tego zasobu". Niezależnie od tego, czy wyślesz żądanie PUT raz czy wiele razy, wynikowy zasób będzie zawsze identyczny.
Na przykład rozważmy scenariusz, w którym aktualizujesz adres e-mail użytkownika. Jeśli wysłesz to samo żądanie PUT wiele razy, wynik nie ulegnie zmianie, ponieważ zasób za każdym razem zostaje zastąpiony tymi samymi danymi.
Przykład:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Jeśli wyślesz to żądanie wiele razy, wynik będzie zawsze taki sam:
| {"username": "john_doe","email": "[email protected]"} |
Nawet jeśli dane użytkownika są już takie, ponowne wysłanie żądania nic nie zmienia. Zastępuje dane tymi samymi danymi, więc efekt żądania pozostaje taki sam niezależnie od liczby powtórzeń. To jest właśnie to, co czyni PUT idempotentnym.
Metoda PATCH i idempotentność
Metoda PATCH w REST API, z drugiej strony, jest generalnie również idempotentna, ale z większą elastycznością. Tworząc patche, upewnij się, że operacje są idempotentne (na przykład ustawienie wartości), aby uniknąć niezamierzonych efektów ubocznych z powtarzających się żądań. To, czy PATCH jest idempotentny, zależy od operacji i modyfikowanych danych.
Dlaczego PATCH jest idempotentny? W przypadku żądań PATCH idempotencja oznacza, że wielokrotne zastosowanie tego samego patcha da ten sam wynik. Jest to prawdziwe pod warunkiem, że sam patch nie powoduje dodatkowych efektów ubocznych lub zmian przy powtarzającym się zastosowaniu. Jeśli ciągle stosując ten sam patch z tymi samymi danymi, wynik powinien pozostać niezmieniony po pierwszym zastosowaniu.
Na przykład, jeśli aktualizujesz tylko adres e-mail użytkownika, wielokrotne wysłanie tego samego żądania PATCH nie zmieni wyniku po pierwszym razie, nawet jeśli żądanie zostanie wysłane kilkakrotnie. Adres e-mail użytkownika pozostanie taki sam, a stan zasobu się nie zmieni.
Przykład PATCH API:
| PATCH /users/1{"email": "[email protected]"} |
Jeśli adres e-mail już wynosi [email protected], zastosowanie tego PATCH ponownie nie spowoduje żadnych zmian, co czyni go idempotentnym.
Jednak PATCH może również być nieIdempotentny w niektórych przypadkach. Na przykład, jeśli operacja PATCH modyfikuje licznik lub dodaje elementy do listy (takie jak inkrementacja liczby lub dołączanie do tablicy), wielokrotne zastosowanie tego samego PATCH może prowadzić do różnych wyników. To naruszałoby właściwość idempotencji.
Przykład PATCH nieIdempotentny API REST:
| PATCH /counter/1{"increment": 1} |
Jeśli zastosujeszPATCH wielokrotnie, licznik będzie się dalej zwiększać, za każdym razem dając inne wartości. To nie jest idempotentne, ponieważ rezultat zmienia się z każdym zastosowaniem.
Teraz, gdy znasz już podstawy, możemy przeanalizować kilka przykładowych scenariuszy, aby lepiej zrozumieć różnicę między PUT a PATCH w REST APIs.
Przykładowe scenariusze: PUT vs PATCH w REST API
Pominąwszy teorię, spójrzmy na różnicę między PUT a PATCH na konkretnych przykładach, obejmując zarówno operacje idempotentne, jak i nieide mpotentne.
Scenariusz 1: Żądanie PUT – Zastąpienie całego zasobu
Wyobraź sobie punkt końcowy API do zarządzania produktami w systemie handlu elektronicznego. Musisz zaktualizować wszystkie dane produktu: nazwę, cenę i opis. To typowy przykład porównania metod PUT a PATCH w HTTP, gdzie PUT służy do zastąpienia całego zasobu produktu.
Produkt początkowy
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Chcesz zaktualizować cenę i opis produktu. Wysyłasz żądanie PUT z całym zasobem:
Żądanie PUT:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Jeśli wyślesz to żądanie PUT raz lub wiele razy, rezultat zawsze będzie taki sam. Dane produktu zostaną zaktualizowane z nową ceną i opisem, i ten sam wynik pojawi się za każdym razem. To gwarantuje idempotentność PUT.
Rezultat (po żądaniu PUT):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Scenariusz 2: Żądanie PATCH – Aktualizacja części zasobu
Teraz rozważ żądanie PATCH do aktualizacji tylko części danych produktu, na przykład opisu. Przykład PATCH API: jeśli chcesz zmienić tylko opis produktu bez zmiany ceny, PATCH to lepszy wybór. Aby to zaimplementować, tworzysz patche zawierające tylko pola wymagające modyfikacji, takie jak opis w tym przykładzie API REST PATCH.
Produkt początkowy
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Żądanie PATCH:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Gdy wyślesz to żądanie PATCH, zaktualizowany zostanie tylko field opisu. Jeśli wyślesz to samo żądanie PATCH wiele razy, opis pozostanie niezmieniony po pierwszej aktualizacji, co sprawia, że żądanie jest idempotentne.
Rezultat (po żądaniu PATCH):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Jeśli zastosujeszPATCH ponownie, opis produktu będzie taki sam jak po pierwszym PATCH. Rezultat jest spójny, co sprawia, że PATCH jest w tym scenariuszu idempotentny.
Scenariusz 3: Żądanie PATCH – Operacja nieide mpotentna
Spójrzmy na nieide mpotentną operację PATCH. Załóżmy, że istnieje punkt końcowy do salda portfela użytkownika i chcesz zwiększyć saldo. Różnicę między PUT a PATCH można tutaj zilustrować: PATCH dodaje wartość do salda za każdym razem
Portfel początkowy:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
Żądanie PATCH:
| PATCH /users/1/wallet{"increment": 50.00} |
To żądanie PATCH zwiększy saldo portfela o 50 dolarów. Jeśli wyślesz to żądanie PATCH wiele razy, saldo będzie się dalej zwiększać z każdym PATCH, dając za każdym razem inny rezultat. To nie jest idempotentne, ponieważ wielokrotne zastosowanie tego samego PATCH daje za każdym razem inny wynik.
Rezultat (po pierwszym żądaniu PATCH):
| {"id": 1,"balance": 150.00} |
Rezultat (po drugim żądaniu PATCH):
| {"id": 1,"balance": 200.00} |
PATCH nie jest idempotentny, ponieważ powtórzone żądania z tymi samymi danymi dają różne wyniki.
Podsumowanie: kluczowe różnice między PUT a PATCH w REST API
Kluczowa różnica między PUT a PATCH w REST API to sposób obsługi aktualizacji. PUT zastępuje całego zasobu, więc brakujące pola są usuwane, co może prowadzić do utraty danych. Dlatego programiści tworzą patche do aktualizacji częściowych, aby uniknąć nadpisania niezmiennych pól i zachować integralność danych.
Dzięki temu PATCH jest bardziej wydajny dla aktualizacji częściowych. Przykład PATCH API to sytuacja, gdy chcesz zaktualizować tylko email użytkownika. Za pomocą patcha wyślesz tylko pole email, w przeciwieństwie do żądania PUT, które wymagałoby całych danych użytkownika.
W PUT pełna ładowność danych jest wymagana. Każde pole musi być wysłane, a brakujące pola zostaną usunięte. PATCH natomiast wysyła tylko pola, które trzeba zaktualizować, co czyni go bardziej wydajnym, szczególnie dla dużych zasobów z minimalnymi zmianami. Metoda PATCH w REST API pozwala na bardziej ukierunkowane i mniejsze żądania, zmniejszając transfer danych.
Zarówno PUT jak i PATCH są idempotentne. Oznacza to, że powtórzenie tego samego żądania da ten sam wynik. Jednak PUT jest bardziej przewidywalny, ponieważ zastępuje cały zasób. PATCH, gdy jest używany do zmiany tylko określonych pól, może prowadzić do różnych wyników w zależności od tego, jak serwer obsługuje aktualizacje.
Na przykład, jeśli PATCH zwiększa licznik, powtórzone żądania mogą dać różne wyniki. Niemniej jednak operacje PATCH API można zaprojektować, aby były również idempotentne.
Podsumowując, różnica między PUT a PATCH w REST API sprowadza się do charakteru aktualizacji: PATCH to zmiany częściowe, a PUT to pełna zamiana zasobu. Oba są idempotentne, ale PATCH może być bardziej złożony.
Ostateczne Przemyślenia
Zarówno PUT jak i PATCH to fundamentalne metody HTTP w projektowaniu REST API, ale służą różnym celom, co jest istotą różnicy między PUT a PATCH w REST API. Możesz znacznie poprawić wydajność, przejrzystość i funkcjonalność swojego API, rozumiejąc różnicę między PUT a PATCH na przykładach omówionych wcześniej w tym artykule. Wybierając właściwą metodę (PATCH vs aktualizacja REST) na podstawie Twojego przypadku użycia, możesz sprawić, że Twój API będzie bardziej wydajny, łatwy w utrzymaniu i przyjazny dla użytkownika. Zawsze bierz pod uwagę charakter aktualizacji - czy jest pełna czy częściowa - wraz z wpływem na wydajność i integralność danych, i wybierz metodę, która najlepiej odpowiada Twoim potrzebom.
