Различия

Показаны различия между двумя версиями страницы.

--- software:development:web:docs:web:api:rest_api [2025/10/13 14:43] – [Использование HTTP методов для создания RESTful сервисов] vladpolskiy
+++ software:development:web:docs:web:api:rest_api [2025/10/13 14:54] (текущий) – внешнее изменение 127.0.0.1
@@ Строка 436: / Строка 436: @@
   #content-1:has(~ .tab-nav_new > #tab-btn-1:checked),
   #content-2:has(~ .tab-nav_new > #tab-btn-2:checked),
-  #content-3:has(~ .tab-nav_new > #tab-btn-3:checked) {
+  #content-3:has(~ .tab-nav_new > #tab-btn-3:checked),
+  #content-4:has(~ .tab-nav_new > #tab-btn-4:checked),
+  #content-5:has(~ .tab-nav_new > #tab-btn-5:checked) {
     display: block;
   }
@@ Строка 473: / Строка 475: @@
   <div class="tab_new">
     <div class="tab-content_new" id="content-1">
-      Содержимое 1... Lorem ipsum (/ˌlɔː.rəm ˈɪp.səm/ LOR-əm IP-səm) is a dummy or placeholder text commonly used in graphic design, publishing, and web development. Its purpose is to permit a page layout to be designed, independently of the copy that will subsequently populate it, or to demonstrate various fonts of a typeface without meaningful text that could be distracting.
+      HTTP метод GET используется для получения (или чтения) представления ресурса. В случае „удачного” (или не содержащего ошибок) адреса, GET возвращается представление ресурса в формате XML или JSON в сочетании с кодом состояния HTTP 200 (OK). В случае наличия ошибок обычно возвращается код 404 (NOT FOUND) или 400 (BAD REQUEST).
+</br></br>
+В соответствии спецификации HTTP, GET (так же как и HEAD) запросы используются только для чтения данных, не изменяя их. Таким образом, при соблюдении данного соглашения, они считаются безопасными. То есть они могут использоваться без риска изменения данных, вне зависимости от того, один раз данные были получены, или же 10, или ни разу вовсе. GET (а также HEAD) запросы являются идемпотентными (тождественными), что подразумевает получение идентичных данных при использовании одних и тех же запросов (как при единичном обращении, так и при многократном).
+</br></br>
+Не стоит использовать GET для небезопасных операций над данными, при данном запросе они не должны быть модифицированы.
+</br></br>
+Примеры:
+</br></br>
+GET http://www.example.com/customers/12345</br>
+GET http://www.example.com/customers/12345/orders</br>
+GET http://www.example.com/buckets/sample</br></br>
     </div>
     <div class="tab-content_new" id="content-2">
-      Содержимое 2... Lorem ipsum dolor sit, amet consectetur adipisicing elit. Similique eaque iure debitis nostrum,
+      Метод PUT обычно используется для предоставления возможности обновления ресурса. Тело запроса при отправке PUT-запроса к существующему ресурсу URI должно содержать обновленные данные оригинального ресурса (полностью, или только обновляемую часть).
-      vero ad totam ratione sequi! Suscipit, labore repellat cum soluta ullam dignissimos perspiciatis sequi rerum
+</br></br>
-      sapiente ex.
+Кроме того, PUT может быть использован для создания ресурса, в случае, когда идентификатор ресурса выбирает клиент, а не сервер. Или, если перефразировать — при отправке PUT запроса по адресу, содержащему не существующий идентификатор ресурса. Опять же, стоит помнить, что тело запроса должно быть модификацией оригинального ресурса. Многие считают это запутанным и непонятным. Соответственно, данную возможность метода PUT стоит использовать с осторожностью. Да и при крайней необходимости.
+</br></br>
+Для создания новых экземпляров ресурса предпочтительнее использование POST запроса. В данном случае, при создании экземпляра будет предоставлен корректный идентификатор экземпляра ресурса в возвращённых данных об экземпляре.
+</br></br>
+При успешном обновлении посредством выполнения PUT запроса возвращается код 200 (или 204 если не был передан какой-либо контент в теле ответа). Если PUT используется для создания экземпляра — обычно возвращают HTTP код 201 при успешном создании. Возвращать данные в ответ на запрос необязательно. Также не обязательно возвращать ссылку на экземпляр ресурса посредством заголовка `Location` по причине того, что клиент и так обладает идентификатором экземпляра ресурса.
+</br></br>
+PUT не безопасная операция, так как вследствие её выполнения происходит модификация (или создание) экземпляров ресурса на стороне сервера, но этот метод идемпотентен. Другими словами, создание или обновление ресурса посредством отправки PUT запроса — ресурс не исчезнет, будет располагаться там же, где и был при первом обращении, а также, многократное выполнение одного и того же PUT запроса не изменит общего состояния системы (за исключением первого раза, но это обычно опускают из рассмотрения)
+</br></br>
+Если PUT запрос используется для увеличения счётчика просмотра конкретного ресурса — данный запрос уже не считается идемпотентным. Иногда такое происходит и считается достаточным задокументировать тот факт, что вызов не идемпотентен. Однако строго рекомендуется выдерживать идемпотентность PUT запроса.
+</br></br>
+Примеры:
+</br></br>
+PUT http://www.example.com/customers/12345</br>
+PUT http://www.example.com/customers/12345/orders/98765</br>
+PUT http://www.example.com/buckets/secret_stuff</br></br>
     </div>
     <div class="tab-content_new" id="content-3">
-      Содержимое 3... Lorem ipsum dolor sit, amet consectetur adipisicing elit. Similique eaque iure debitis nostrum,
+      PATCH запрос используется для **модификации** ресурса. PATCH запрос должен содержать только изменяемые данные ресурса, а не все его данные.
-      vero ad totam ratione sequi! Suscipit, labore repellat cum soluta ullam dignissimos perspiciatis sequi rerum
+</br></br>
-      sapiente ex.
+Это напоминает работу PUT запроса, но в теле запроса содержится набор инструкций описывающих как должен быть изменён ресурс, расположенный на сервере, для формирования новой версии. Это означает, что тело PATCH запроса должно содержать не просто изменения ресурса, а представлять из себя описание на языке внесения изменений (patch language) таких как JSON Patch или XML Patch.
+</br></br>
+PATCH запрос ни является безопасным, ни идемпотентным. Однако PATСH запрос может быть сформирован таким образом чтобы быть идемпотентным, что в свою очередь помогает предотвратить негативные последствия от коллизий между двумя PATCH запросами к одному и тому же ресурсу в один и тот же промежуток времени. Коллизии нескольких PATCH запросов могут быть более опасными чем коллизии PUT запросов, потому что некоторым форматам изменений необходимо выполняться от известной базовой-точки или ресурс будет поврежден. Клиенты, использующие такой тип внесения изменений, должны использовать условный запрос на проверку изменения ресурса с момента последнего доступа клиента к нему. Например клиент может использовать ETag в заголовке If-Match в самом PATСH запросе.
+</br></br>
+Примеры:
+</br></br>
+PATCH http://www.example.com/customers/12345</br>
+PATCH http://www.example.com/customers/12345/orders/98765</br>
+PATCH http://www.example.com/buckets/secret_stuff</br></br>
+    </div>
+        <div class="tab-content_new" id="content-4">
+      POST запрос наиболее часто используется для создания новых ресурсов. На практике он используется для создания вложенных ресурсов. Другими словами, при создании нового ресурса, POST запрос отправляется к родительскому ресурсу и, таким образом, сервис берет на себя ответственность на установление связи создаваемого ресурса с родительским ресурсом, назначение новому ресурсу ID и т.п.
+</br></br>
+При успешном создании ресурса возвращается HTTP код 201, а также в заголовке `Location` передается адрес созданного ресурса.
+</br></br>
+POST не является безопасным или идемпотентным запросом. Потому рекомендуется его использование для не идемпотентных запросов. В результате выполнения идентичных POST запросов предоставляются сильно похожие, но не идентичные данные.
+</br></br>
+Примеры:
+</br></br>
+POST http://www.example.com/customers</br>
+POST http://www.example.com/customers/12345/orders</br></br>
+    </div>
+        <div class="tab-content_new" id="content-5">
+      DELETE запрос крайне прост для понимания. Он используется для удаления ресурса, идентифицированного конкретным URI (ID).
+</br></br>
+При успешном удалении возвращается 200 (OK) код HTTP, совместно с телом ответа, содержащим данные удалённого ресурса (отрицательно сказывается на экономии трафика) или завернутые ответы (Смотрите "Возвращаемые данные"). Также возможно использование HTTP кода 204 (NO CONTENT) без тела ответа.
+</br></br>
+Согласно спецификации HTTP, DELETE запрос идемпотентен. Если вы выполняете DELETE запрос к ресурсу, он удаляется. Повторный DELETE запрос к ресурсу закончится также: ресурс удалён. Если DELETE запрос используется для декремента счётчика, DELETE запрос не является идемпотентным. Используйте POST для неидемпотентных операций.
+</br></br>
+Тем не менее, существует предостережение об идемпотентности DELETE. Повторный DELETE запрос к ресурсу часто сопровождается 404 (NOT FOUND) кодом HTTP по причине того, что ресурс уже удалён (например из базы данных) и более не доступен. Это делает DELETE операцию не идемпотентной, но это общепринятый компромисс на тот случай, если ресурс был удалён из базы данных, а не помечен, как удалённый.
+</br></br>
+Примеры:
+</br></br>
+DELETE http://www.example.com/customers/12345</br>
+DELETE http://www.example.com/customers/12345/orders</br>
+DELETE http://www.example.com/bucket/sample</br>
     </div>
     <div class="tab-nav_new">