В этом посте обещал вернуться с более подробным разбором памятки, если будет такой запрос — возвращаюсь!

На изображении примеры запроса(Request) и ответа(Response). Самое главное, на что стоит обратить внимание: Все запросы и ответы состоят из заголовков и тела: - Заголовки — это метаданные для передачи сервисной информации о запросе. По крайней мере так обычно принято их использовать. Реже их используют для передачи бизнес-данных, но тоже используют, и в отдельных кейсах это может быть оправдано и полезно. В заголовки можно класть информацию о формате данных в теле и его кодировке, данные о клиенте(не путать с пользователем), данные о пользователе(куки, токены и тд), данные о версии API и тд. - Тело — здесь обычно передают бизнес-данные. Формат передачи может быть сильно разный, например, JSON, YAML, Plain text(обычный текст), Binary(двоичный формат) и тд. Тело является опциональным атрибутом в запросе и ответе с точки зрения протокола, но с точки зрения стиля REST, все зависит от метода в запросе, об этом дальше.

Запросы всегда содержат метод. Но перед этим надо разобраться: Что такое безопасный метод? Это метод, который не производит изменений на сервере. Например, получение данных(GET) — безопасно, а вот создание(POST) — небезопасно.

Что такое идемпотентный метод? Метод, при повторном вызове которого идентичным запросом, возвращается один и тот же результат, не производя повторные изменения на сервере. Метод может быть идемпотентным из коробки, как например GET, а может стать идемпотентным искусственно за счет реализации проверок на сервере и добавления специального ключа. Обычно искусственную идемпотентность делают для метода POST.

В REST всего пять методов: - POST — создает ресурсы, поэтому всегда содержит тело в запросе и обычно содержит тело в ответе с результатом созданных данных. Метод является небезопасным, так как может создавать новые данные, а также из коробки является неидемпотентным. - GET — предоставляет данные по ресурсу, поэтому всегда имеет пустое тело в запросе, но содержит тело в ответе с запрашиваемыми данными. Метод является безопасным, так как не изменяет и не создает ресурсы, а также является из коробки идемпотентным. - PUT — изменяет ресурс полностью по его идентификатору, всегда содержит тело в запросе и обычно содержит тело в ответе с результатом. Метод является небезопасным, так как изменяет ресурсы, а также из коробки является идемпотентным. - PATCH — частично изменяет ресурс по его идентификатору, всегда содержит тело в запросе и обычно содержит тело в ответе с результатом. Метод является небезопасным, так как изменяет ресурсы, а также является идемпотентным. В зависимости от реализации может быть неидемпотентным, старайтесь просто не использовать данный метод, так как не смотря на его простую функциональность, на самом деле метод усложняет всем жизнь. - DELETE — удаляет ресурс по его идентификатору, поэтому всегда имеет пустое тело в запросе, но содержит тело в ответе с удаленными данными. Метод является небезопасным, так как удаляет данные, а также из коробки является идемпотентным, так как повторное использование DELETE с тем же id ни к чему не приведет, однако, в зависимости от реализации, может вызвать ошибку.

Еще в запросе должен содержаться ресурс, к которому мы обращаемся для его создания, получения или изменения(если используется стиль REST). Ресурс это часть URI. Опционально и в зависимости от реализации в URI также может содержаться версия API, к которой обращается клиент и параметры, на основе которых выполняется фильтрация или пагинация.

В ответе всегда есть статус. Он состоит из кода и короткого сообщения. Например, при успешно отработанном запросе возвращается код "200" и сообщение "OK". Подробнее по распрастраненным кодам писал тут.

#быстростатья #REST #API