REST API с JSON

Что такое REST API?

REST расшифровывается как Re Presenalal S tate Transfer. Он опирается на клиент-серверную кешируемую связь без сохранения состояния. В большинстве случаев это используется с протоколом HTTP.

Приложения RESTful используют HTTP-запросы для POST (создание), PUT (создание и / или обновление), GET (например, создание запросов) и DELETE данных. REST использует HTTP для всех четырех операций CRUD (создание / чтение / обновление / удаление).

Что такое JSON?

JSON (JavaScript Object Notation) — это легкий формат обмена данными. Людям легко читать и писать. Машины легко разбираются и генерируются.

протоколы

HTTP позволяет использовать разные протоколы для связи между клиентом и сервером. Мы не будем объяснять все из них, но четыре наиболее часто используемых: GET, PUT, POST и DELETE.

GET, PUT и DELETE должны быть реализованы как идемпотентные методы. Независимо от того, сколько раз запросы повторяются, результат должен быть одинаковым. POST, с другой стороны, не должен быть идемпотентным.

ПОЛУЧИТЬ

GET выполняет какой-то запрос. Он не запрашивает никаких изменений в состоянии системы ни в какой форме или способом. Это не означает, что сервер не выполняет какое-либо изменение своего состояния, но клиент не запрашивал его. При выполнении запроса GET сервер должен ответить с результатом в форме JSON.

ПОЧТА

POST — это запрос на создание нового объекта. Содержимое этого объекта должно быть включено в тело запроса.

ПОЛОЖИТЬ

PUT похож на POST с той разницей, что он должен создать новую сущность, если она не существует, или изменить существующую.

УДАЛИТЬ

DELETE — это запрос на удаление указанного объекта с сервера.

Запросы к серверу

Избегайте использования не существительных, таких как getAllBooks или createNewBook. Тип действия, которое нужно выполнить, указывается с помощью HTTP-методов GET, POST, PUT и DELETE. URI должен указывать объект, с которым должны выполняться операции. Например, GET / books должен получать книги с сервера, DELETE / books должен удалять книгу, PUT / books должен изменять или создавать книгу, а POST / book должен запрашивать создание книги на сервере.

В случае метода GET остальная часть URI должна предоставлять информацию относительно типа сервера запросов, который следует использовать для извлечения запрошенных данных. Используйте параметры запроса в самом URI. Например, / books должен вернуть все книги. / books / id / 24 должен вернуть книгу, идентифицированную с идентификатором 24. / books / pageSize / 25 должен вернуть только 25 книг.

Остальные методы (POST, PUT и DELETE) должны иметь всю информацию, заключенную в теле сообщения в формате JSON.

Аналогично методу GET, DELETE может применяться к одним конкретным данным, подмножеству данных или ко всем из них (если это разрешено сервером). Если кто-то захочет удалить одну книгу DELETE / book request, в теле будет JSON {id: 24} . Точно так же, если кто-то захочет удалить книги, которые соответствуют более широким критериям, JSON будет Наконец, если нет тела, все книги будут удалены.

POST и PUT работают аналогично, как DELETE. В теле запроса есть информация о том, что должно быть создано или изменено. Можно поместить одну сущность в тело запроса PUT / books . Этот запрос может создать или изменить одну книгу. Примером может служить Если массовая вставка разрешена, несколько сущностей могут быть переданы в виде массива

Имейте в виду, что сервер отвечает за проверку того, разрешен или нет какой-либо запрос. Операция удаления более одной книги может быть ограничена только определенными пользователями, и запрос DELETE без тела (удалить все) может быть отклонен для всех пользователей. Конечная ответственность за решение о том, разрешен или нет запрос, находится в руках сервера.

В итоге GET не имеет тела и использует URI для указания сущности (т. Е. / Books) и, при необходимости, дополнительных параметров запроса (т. Е. Id / 24). POST, PUT и DELETE не должны указывать параметры запроса через URI, а использовать тело сообщения для передачи информации о том, что должно быть создано, изменено или удалено.

Ответы с сервера

Ответы от сервера должны быть всегда в формате JSON и согласованными. Они всегда должны содержать метаинформацию и, необязательно, данные. Согласованность позволяет потребителям нашего API знать, чего ожидать. Кроме того, это позволяет нам писать меньше кода реализации, поскольку некоторый анализ может быть выполнен унифицированно для всех типов запросов.

HTTP-ответ уже содержит состояние (дополнительную информацию о кодах состояния можно найти в определениях кодов состояния ). Мы можем улучшить это с помощью метаинформации, которая может содержать дополнительную информацию. Дополнительная информация, специфичная для реализации на сервере, может быть предоставлена, например, с ошибкой и сообщением. Как правило, когда клиент получает ответ со статусом HTTP 2XX, запрос был успешным. Ответы со статусом 4XX представляют ошибки, спровоцированные клиентом (т.е. отсутствуют обязательные данные), а 5XX — ошибки сервера.

Данные должны быть указаны, даже если они не отправлены с сервера.

Несколько примеров будет:

Versioning

Поскольку API не будет единственной точкой входа для HTTP-запросов, часто рекомендуется отличать URI API от других. Я склонен ставить префикс api для всех URI.

Важно понимать, что как только API публикуется, и другие начинают его использовать, мы должны убедиться, что будущие изменения не нарушат использование для тех, кто не обновил своих клиентов соответствующим образом. По этой причине хорошей практикой является префикс всех URI API с номером версии. Первый может называться v1, следующий v2 и так далее. Таким образом, у нас будет свобода для реализации изменений, которые могут потенциально привести к несовместимости в качестве отдельного URI.

Учитывая эти две вещи, наш предыдущий пример с книгой будет выглядеть примерно так: / api / v1 / books

Примеры

Наконец, давайте рассмотрим несколько примеров с книгами.

Запросить список книг

Протокол: GET
URI: / api / v1 / books
Тело запроса: ПУСТО
Отклик:

Описание: запрашивает все книги, которые будут получены с сервера.

Заказать одну книгу

Протокол: GET
URI: / api / v1 / books / id / 24
Тело запроса: ПУСТО
Отклик:

Описание: запрашивает книгу с идентификатором 24 для получения с сервера.

Заказать создание книги

Протокол: POST
URI: / api / v1 / books
Тело запроса:

Ответ со статусом 201:

Описание: Запрашивает создание книги. Ответ сервера — 201 (создан) с URI, который может использоваться клиентом для получения запрошенной книги.

Запросить создание или изменение книги

Протокол: PUT
URI: / api / v1 / books
Тело запроса:

Ответ со статусом 412:

Описание: Запрашивает изменение или создание книги. Ответ сервера 412 (предварительное условие не выполнено) с кодом ошибки и сообщением, описывающим проблему.

Запросить удаление книги

Протокол: УДАЛИТЬ
URI: / api / v1 / books
Тело запроса:

Ответ со статусом 202:

Описание: Запрашивает удаление книги. Ответ сервера 202 (принято), что означает, что сервер принял запрос, но обработка не была завершена. Другими словами, сервер ответил немедленно и ожидает удаления.