В этом посте обещал вернуться с более подробным разбором памятки, если будет такой запрос — возвращаюсь!
На изображении примеры запроса(Request) и ответа(Response). Самое главное, на что стоит обратить внимание:
Все запросы и ответы состоят из заголовков и тела:
▶️Заголовки — это метаданные для передачи сервисной информации о запросе. По крайней мере так обычно принято их использовать. Реже их используют для передачи бизнес-данных, но тоже используют, и в отдельных кейсах это может быть оправдано и полезно. В заголовки можно класть информацию о формате данных в теле и его кодировке, данные о клиенте(не путать с пользователем), данные о пользователе(куки, токены и тд), данные о версии API и тд.
▶️Тело — здесь обычно передают бизнес-данные. Формат передачи может быть сильно разный, например, JSON, YAML, Plain text(обычный текст), Binary(двоичный формат) и тд. Тело является опциональным атрибутом в запросе и ответе с точки зрения протокола, но с точки зрения стиля REST, все зависит от метода в запросе, об этом дальше.
Запросы всегда содержат метод. Но перед этим надо разобраться:
❓Что такое безопасный метод?
Это метод, который не производит изменений на сервере. Например, получение данных(GET) — безопасно, а вот создание(POST) — небезопасно.
❓Что такое идемпотентный метод?
Метод, при повторном вызове которого идентичным запросом, возвращается один и тот же результат, не производя повторные изменения на сервере. Метод может быть идемпотентным из коробки, как например GET, а может стать идемпотентным искусственно за счет реализации проверок на сервере и добавления специального ключа. Обычно искусственную идемпотентность делают для метода POST.
В REST всего
1️⃣
POST — создает ресурсы, поэтому всегда содержит тело в запросе и обычно содержит тело в ответе с результатом созданных данных. Метод является небезопасным, так как может создавать новые данные, а также из коробки является неидемпотентным.2️⃣
GET — предоставляет данные по ресурсу, поэтому всегда имеет пустое тело в запросе, но содержит тело в ответе с запрашиваемыми данными. Метод является безопасным, так как не изменяет и не создает ресурсы, а также является из коробки идемпотентным.3️⃣
PUT — изменяет ресурс полностью по его идентификатору, всегда содержит тело в запросе и обычно содержит тело в ответе с результатом. Метод является небезопасным, так как изменяет ресурсы, а также из коробки является идемпотентным.4️⃣
PATCH — частично изменяет ресурс по его идентификатору, всегда содержит тело в запросе и обычно содержит тело в ответе с результатом. Метод является небезопасным, так как изменяет ресурсы, а также является идемпотентным. В зависимости от реализации может быть неидемпотентным, старайтесь просто не использовать данный метод, так как не смотря на его простую функциональность, на самом деле метод усложняет всем жизнь.5️⃣
DELETE — удаляет ресурс по его идентификатору, поэтому всегда имеет пустое тело в запросе, но содержит тело в ответе с удаленными данными. Метод является небезопасным, так как удаляет данные, а также из коробки является идемпотентным, так как повторное использование DELETE с тем же id ни к чему не приведет, однако, в зависимости от реализации, может вызвать ошибку.Еще в запросе должен содержаться ресурс, к которому мы обращаемся для его создания, получения или изменения(если используется стиль REST). Ресурс это часть URI. Опционально и в зависимости от реализации в URI также может содержаться версия API, к которой обращается клиент, и параметры, на основе которых выполняется фильтрация или пагинация.
В ответе всегда есть статус. Он состоит из кода и короткого сообщения. Например, при успешно отработанном запросе возвращается код "
200 OK". Подробнее по распрастраненным кодам писал тут.#быстростатья #REST #API