update state, api, arch

docs/api/03-rest-api.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 3
+---
+
+# REST API
+
+**REST API** (Representational State Transfer Application Programming Interface) — это архитектурный стиль для создания веб-сервисов, который основывается на стандартных протоколах и методах HTTP. REST API используется для взаимодействия между клиентом и сервером, где клиент отправляет запросы, а сервер возвращает ответы в формате, обычно JSON или XML.
+
+## Основные принципы REST API:
+1. **Ресурсы (Resources):**
+   - Все данные рассматриваются как ресурсы, которые идентифицируются с помощью URL (например, `/users`, `/products`).
+   - Каждый ресурс имеет уникальный идентификатор (URI).
+2. **HTTP-методы:**
+   - Используются стандартные HTTP-методы для выполнения операций:
+     - `GET` — получение данных.
+     - `POST` — создание нового ресурса.
+     - `PUT` — обновление существующего ресурса.
+     - `DELETE` — удаление ресурса.
+     - `PATCH` — частичное обновление ресурса.
+3. **Статус ответа:**
+   - Сервер возвращает HTTP-коды состояния, которые указывают на результат выполнения запроса:
+     - `200 OK` — успешный запрос.
+     - `201 Created` — ресурс успешно создан.
+     - `400 Bad Request` — неверный запрос.
+     - `404 Not Found` — ресурс не найден.
+     - `500 Internal Server Error` — ошибка на сервере.
+4. **Без состояния (Stateless):**
+   - Каждый запрос от клиента к серверу должен содержать всю необходимую информацию для его обработки. Сервер не хранит состояние клиента между запросами.
+5. **Кэширование:**
+   - Ответы сервера могут быть кэшированы для повышения производительности.
+6. **Единообразие интерфейса:**
+   - API должен быть простым и понятным, с использованием стандартных подходов.
+7. **Форматы данных:**
+   - RESTful API обычно использует JSON или XML для передачи данных между клиентом и сервером.
+
+## Пример REST API:
+Предположим, у нас есть API для управления пользователями:
+- `GET /users` — получить список всех пользователей.
+- `GET /users/1` — получить информацию о пользователе с ID 1.
+- `POST /users` — создать нового пользователя (тело запроса содержит данные пользователя).
+- `PUT /users/1` — обновить информацию о пользователе с ID 1.
+- `DELETE /users/1` — удалить пользователя с ID 1.
+
+## Преимущества REST API:
+- **Простота:** Использует стандартные HTTP-методы и статусы.
+- **Масштабируемость:** Подходит для больших и распределенных систем.
+- **Гибкость:** Поддерживает различные форматы данных (JSON, XML).
+- **Кэширование:** Улучшает производительность за счет кэширования ответов.
+- **Независимость от платформы:** Может использоваться с любым языком программирования или технологией.
+
+## Разница между REST API и RESTful API:
+- **REST API** — это общий термин, описывающий API, которое следует принципам REST.
+- **RESTful API** — это более строгий термин, подразумевающий, что API полностью соответствует всем принципам REST.