# REST API

**REST** (Representational State Transfer) – это архитектурный стиль взаимодействия компонентов распределённого приложения в сети. Архитектурный стиль – это набор согласованных ограничений и принципов проектирования, позволяющий добиться определённых свойств системы.

### **Принципы REST API**

1. **Клиент-серверная архитектура.**
2. **Stateless.** В противовес **Stateful**, сервер не хранит у себя информацию о сессии с клиентом и о его предыдущих обращениях. В каждом запросе сервер получает всю необходимую информацию для обработки.
3. Кэширование.
4. **Единообразие интерфейса** (HATEOAS). Сервер возвращает не только ресурс, но также его связи с другими ресурсами и действия, которые можно с ним совершить.
5. **Layered system** (слоистая система). Ни клиент, ни сервер не должны знать о том, как происходит цепочка вызовов дальше своих прямых соседей.
6. **Code on demand** (код по запросу). В ответ на запрос клиента сервер передаёт исполняемый код (программу), который может быть выполнен на его, клиента, стороне.

### **Уровни зрелости REST API**

* **Уровень 0.** API использует протокол HTTP и любой формат передачи данных, все запросы идут к одному URL и через один метод.
* **Уровень 1.** Запросы идут к разным URL, но по-прежнему используют один метод.
* **Уровень 2.** Запросы идут к разным URL и используют разные методы.
* **Уровень 3.** Реализована концепция HATEOAS.

### **Проектирование REST API**

1. Определите, какие объекты на сервере доступны клиенту.
2. Назначьте URL-адреса этим объектам. По общему правилу, каждому объекту назначается два адреса:

* название объекта во множественном числе (**/orders**);
* название ресурса во множественном числе + уникальный идентификатор одного ресурса (**/orders/\<order\_id>**).

Эти адреса называются **endpoints** (конечные точки), к ним клиент отправляет запросы.

3. Определите, какие действия с объектами могут быть выполнены. Каждому endpoint назначьте один или несколько HTTP-запросов и опишите, что делают эти запросы.
4. Определите, какими данными могут обмениваться клиент и сервер (допустимый формат данных, headers, body).

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FRDm6ZHg2RPIo3WhtDi0z%2Fimage.png?alt=media&#x26;token=09f11941-3aa8-4631-b698-f2c8f2219296" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2F8rlPTsNVTUowzvhS7Tjc%2Fimage.png?alt=media&#x26;token=59906075-8ee3-40f4-86e1-b2e079ba909e" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2Fe2PYOAmUXa2w4zBsrtsJ%2Fimage.png?alt=media&#x26;token=959d9c75-ff65-4450-93af-ada4e3175234" alt=""><figcaption></figcaption></figure></div>

Связывать объекты в запросах можно разными способами, например:

<div align="left"><figure><img src="https://956387675-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FczgjL0lfenykQjm6DQfO%2Fuploads%2FzmnCSdlOIFnsRg6nMTKr%2Fimage.png?alt=media&#x26;token=58fc443c-b000-411c-9570-f292155d7e5b" alt=""><figcaption></figcaption></figure></div>

### **Типы интеграций**

1. **Интеграция, управляемая клиентом.** Пользователь нажимает кнопку в приложении – клиент отправляет запрос серверу.
2. **Интеграция, управляемая сервером:**

* **Polling** (опрос). Клиент с заданной периодичностью оправляет серверу один и тот же запрос. В ответе сервер уведомляет клиента о состоянии ресурса.
* **Long polling** (долгий опрос). Клиент отправляет серверу запрос, а сервер отвечает тогда, когда что-то изменится.
* **Webhook** (вебхук). В запросе клиента содержится Callback URL (URL обратного вызова). Когда что-то изменится, сервер посылает запрос на Callback URL.