RestApi

1. Принципы REST
2. Методы HTTP
3. Ресурсы и принципы наименования ресурсов
4. Основные концепции разработки REST API

REST API (Representational State Transfer) — это архитектурный стиль взаимодействия компонентов в сети, который использует стандартные протоколы HTTP. Его принципы помогают создавать масштабируемые, простые и интуитивно понятные веб-сервисы. Вот основные принципы REST API:

1. Клиент-серверная архитектура:

REST предполагает разделение клиента и сервера. Клиенты отправляют запросы серверу для получения или изменения ресурсов, а сервер отвечает на эти запросы. Это разделение позволяет клиентам и серверам развиваться независимо друг от друга.

2. Без сохранения состояния (Stateless)

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

3. Кэширование

Ответы от сервера должны быть явно помечены как кэшируемые или некэшируемые. Это позволяет клиентам кэшировать ресурсы для увеличения производительности, снижения задержек и уменьшения нагрузки на сервер.

4. Единообразие интерфейса (Uniform Interface)

Это один из ключевых аспектов в дизайне REST API. Единообразный интерфейс упрощает и обобщает архитектуру, что облегчает взаимодействие между различными компонентами системы. Это включает в себя:

• Ресурсная идентификация в запросах: Каждый ресурс должен быть идентифицирован по уникальному URI.
• Манипуляция с ресурсами через представления: Клиенты взаимодействуют с ресурсами через представления, которые сервер предоставляет в формате, таком как JSON или XML.
• Самоописательные сообщения: Сообщения, которые содержат достаточно информации для обработки запроса или понимания ответа. Это также включает соответствующие метаданные.
• Гипермедиа как движущая сила состояния приложения (HATEOAS): Клиенты могут динамически навигировать по приложению благодаря гиперссылкам, предоставляемым сервером в ответах.

5. Многоуровневая система (Layered System)

Клиенты взаимодействуют с интерфейсом API, не зная о внутренних слоях сервера, которые обрабатывают запрос. Это позволяет системе развиваться и масштабироваться, вводя новые слои без воздействия на клиент.

6. Код по запросу (optional)

Серверы могут временно расширять или настраивать функциональность клиента, передавая исполняемый код в ответах.

В RESTful архитектуре ресурсы играют ключевую роль.

Ресурс — это объект или представление некоторой информации, которая может быть управляема или доступна через API.

Важной частью разработки RESTful API является правильное именование ресурсов, что облегчает понимание и использование API. Вот основные принципы, касающиеся ресурсов и их именования:

Ресурсы

Ресурсы представляют собой сущности, доступные для взаимодействия в системе. Они обычно представлены с помощью URL и могут быть всем, что имеет значение для системы, например:

• Объекты данных (например, пользователь, заказ, товар)
• Сервисы (например, поиск или аутентификация)
• Коллекции объектов (например, список пользователей)

Каждый ресурс в REST должен иметь уникальный идентификатор (URI), который стабильно указывает на конкретный ресурс или коллекцию ресурсов.

Принципы именования ресурсов

1. Использование существительных, а не глаголов:
• Ресурсы должны быть именами существительными (например, /users, /orders) вместо глаголов или действий. Действия определяются с помощью HTTP-методов (GET для получения, POST для создания, и т.д.).
2. Читаемые и понятные URL:
• URL должны быть интуитивно понятными и легко читаемыми, чтобы другие разработчики могли легко понять структуру API. Например, /users/123/orders намного понятнее, чем /getOrdersByUserId?id=123.
3. Использование множественного числа для коллекций:
• Коллекции или группы ресурсов должны быть именованы во множественном числе (например, /users для коллекции пользователей и /users/123 для конкретного пользователя).
4. Избегание сложных URL:
• Сложные и глубокие иерархии в URL следует избегать. Если иерархия необходима, старайтесь ограничить её разумным уровнем вложенности. Например, /users/123/orders является приемлемым, но добавление дополнительных уровней может усложнить понимание и использование API.
5. Использование гиперссылок для навигации:
• В ответах API используйте HATEOAS (Hypermedia As The Engine Of Application State), что позволяет клиентам динамически навигировать по API через гиперссылки, предоставляемые вместе с данными.

Примеры

• Плохо: /getUserById/123, /createNewOrder
• Хорошо: /users/123, /orders (с использованием POST для создания)

Следование этим принципам помогает создавать организованные, масштабируемые и интуитивно понятные RESTful API, которые легко использовать и интегрировать.

Информационные

• 100 Continue: Сервер получил начальную часть запроса и клиент может продолжать отправку.

Успешные

• 200 OK: Стандартный ответ для успешных HTTP-запросов.
• 201 Created: Запрос успешно выполнен и в результате создан новый ресурс.
• 204 No Content: Запрос успешно обработан, но в ответе нет содержимого.

Перенаправления

• 301 Moved Permanently: Запрашиваемый ресурс был окончательно перемещен в новый URI.
• 302 Found: Запрашиваемый ресурс временно перемещен на другой URI.

Клиентские ошибки

• 400 Bad Request: Сервер не может обработать запрос из-за клиентской ошибки.
• 401 Unauthorized: Для доступа к запрашиваемому ресурсу требуется аутентификация.
• 403 Forbidden: Сервер понял запрос, но отказывается его выполнить.
• 404 Not Found: Запрашиваемый ресурс не найден на сервере.

Серверные ошибки

• 500 Internal Server Error: Неопределенная ошибка сервера, которая не позволяет выполнить запрос.
• 503 Service Unavailable: Сервер временно не доступен, обычно из-за перегрузки или технического обслуживания.

В RESTful API есть несколько ключевых концептов, которые определяют структуру и функциональность запросов и ответов. Эти концепты включают:

• параметры пути (path parameters)
• тело запроса/ответа (request/response body),
• заголовки (headers)
• параметры запроса (query parameters).

Вот более подробное объяснение каждого из этих элементов:

1. Параметры пути (Path Parameters)

Параметры пути используются для идентификации конкретного ресурса или группы ресурсов в API. Они встраиваются непосредственно в URL.
Например, в URL https://api.example.com/users/123, 123 является параметром пути, который указывает на конкретного пользователя с идентификатором 123.

2. Тело запроса/ответа (Request/Response Body)

Тело запроса содержит данные, которые отправляются серверу. В RESTful API тело запроса часто содержит JSON или XML, который представляет собой создаваемый или обновляемый ресурс. Тело ответа — это данные, которые сервер возвращает в ответ на запрос. Это также часто бывает в формате JSON или XML и содержит запрошенную информацию или детали о результате операции.

3. Заголовки (Headers)

Заголовки запроса и ответа содержат метаданные, которые используются для управления запросами и ответами. Заголовки могут включать информацию о типе содержимого (Content-Type), авторизации (Authorization), кэшировании (Cache-Control) и других инструкциях, которые могут влиять на обработку запроса или ответа.

4. Параметры запроса (Query Parameters)

Параметры запроса добавляются в URL после знака вопроса ? и позволяют передать серверу дополнительную информацию, которая может быть использована для фильтрации, сортировки или уточнения данных запроса. Например, https://api.example.com/users?role=admin&status=active использует параметры запроса role и status для фильтрации пользователей по роли администратора и активному статусу.