REST API

1. REST API

Сервер — компьютер со специальным программным обеспечением. Контролем за работой сервера занимается системный администратор.

Дата-центр - специально оборудованная площадка с круглосуточной технической поддержкой для размещенных серверов. Обеспечивает их бесперебойную работу.

Бекенд - программа, расположенная на сервере и способная обработать входящие HTTP-запросы и имеющая набор готовых действий на определенные запросы.

API (интерфейс прикладного программирования) — набор четко определенных правил связи между различными программными компонентами. Интерфейс описывает, что можно попросить программу сделать и что получится в результате.

REST (representational state transfer) — стиль бекенд-архитектуры, основанный на наборе принципов, которые описывают как сетевые ресурсы определяются и адресуются.

REST API — бекенд построенный по принципу REST. Служит прослойкой между веб-приложением и базой данных. Имеет стандартный интерфейс для обращения к ресурсам. Работает как веб-сайт, мы посылаем HTTP-запрос с клиента на сервер, а в ответ, вместо HTML-страницы, получаем данные в JSON-формате.

• Intro to REST (aka. What Is REST Anyway?)

• Do you know what a REST API is?

2. Формат запроса

REST-сервис требует, чтобы клиент делал запрос на добавление, извлечение или изменение данных. Запрос обычно состоит из:

• HTTP-метод — определяет какую операцию выполнять.

• Заголовок — позволяет клиенту передавать информацию о запросе.

• Путь — путь к ресурсу. Доступные пути описываются в документации бекенда.

• Тело — дополнительный блок запроса, содержащий данные.

2.1. HTTP-методы

Выделяют 4 основных метода для работы с REST-сервисом.

• POST — создать новый ресурс.

• GET — получить набор ресурсов или определенный ресурс по идентификатору.

• PUT или PATCH — обновление определенного ресурса по идентификатору.

• DELETE — удаление определенного ресурса по идентификатору.

HTTP-методы на MDN

2.2. Заголовки

Заголовки содержат служебную информацию, относящуюся к пользователю или контенту запроса и как клиент собирается обрабатывать предоставленную ему информацию.

К примеру, тип контента, который клиент может обработать в ответе от сервера (заголовок Accept) или который описывает тип ресурса, который клиент отправляет серверу или сервер отправляет клиенту (заголовок Content-Type).

MIME-типы — варианты типов контента. Используются для указания содержимого запроса и ответа, состоят из типа и подтипа, которые разделены косой чертой /.

Например текстовый файл, содержащий HTML, будет описан типом text/html. Если файл содержит CSS, он будет описан как text/css. Данные в формате JSON будут описаны как application/json. Если клиент ожидает text/css, а получает application/json, он не сможет распознать и обработать контент.

2.3. Пути

Запросы должны содержать путь к ресурсу, над которым выполняется операция. Доступные пути (ендпоинты, ресурсы) описываются в документации бекенда.

https://bookstore.com/api/orders/289
Copy

Такой путь явно указывает ресурс, даже если вы его никогда раньше не видели, потому что он является иерархическим и описательным. Мы обращаемся к заказу с идентификатором 289.

2.4. Коды ответов

На запрос клиента сервер отправляет ответ. Ответ содержит код состояния, чтобы информировать клиента о результате операции. Коды делятся на группы.

• 1XX — несут информационное назначение

• 2XX — коды успешного проведения операции

• 3XX — описывают все, что связано с перенаправлением

• 4XX — указывают на ошибки клиента

• 5XX — указывают на ошибки на стороне сервера

Не нужно помнить каждый код состояния (их много), но необходимо знать наиболее распространенные и их значения.

• 200 (OK) - стандартный ответ для успешных HTTP-запросов

• 201 (Created) - стандартный ответ для HTTP-запроса, который привел к успешному созданию ресурса

• 400 (Bad Request) - запрос не может быть обработан из-за неверного синтаксиса запроса или другой ошибки клиента.

• 401 (Unauthorized) - для доступа к ресурсу требуется авторизация.

• 403 (Forbidden) - у клиента нет разрешения на доступ к этому ресурсу.

• 404 (Not Found) - в настоящее время ресурс не найден. Возможно, он был удален или еще не существует.

• 500 (Internal Server Error) - общий ответ на непредвиденный сбой сервера, если нет более конкретной информации.

Справочник HTTP-кодов

3. Запрос-Ответ

Предположим, у нас есть приложение, которое позволяет просматривать, создавать, редактировать и удалять клиентов и заказы небольшого книжного магазина, бекенд которого размещен на bookstore.com/api. Используя полученные, знания мы можем, псевдокодом описать процесс запрос-ответ к бекенду.

Если бы мы хотели посмотреть всех клиентов, запрос будет выглядеть так.

GET bookstore.com/api/customers
Accept: application/json
Copy

Ответ сервера.

Status: 200 OK
Content-Type: application/json
Body: JSON-данные о всех клиентах
Copy

Для просмотра одного клиента мы указываем его идентификатор.

GET bookstore.com/api/customers/289
Accept: application/json
Copy

Ответ сервера.

Status: 200 OK
Content-Type: application/json
Body: JSON-данные о клиенте
Copy

Создание нового клиента.

POST bookstore.com/api/customers
Content-Type: application/json
Body: { "name": "Mango", "email": "[e-mail]" }
Copy

Сервер добавляет уникальный идентификатор для этого объекта и возвращает его обратно клиенту.

Status: 201 Created
Content-type: application/json
Body: { "id": 18674, "name": "Mango", "email": "[e-mail]" }