Лучшие практики REST API — примеры проектирования конечных точек

В веб-разработке REST API играют важную роль при обеспечении бесперебойной связи между клиентом и сервером.

О клиенте можно думать как о фронтенде, а о сервере  —  как о бэкенде.

Связь между клиентом (интерфейсом) и сервером (серверной частью) обычно не супер-прямая. Поэтому в дело вступает интерфейс, называемый прикладным программным интерфейсом (Application Programming Interface, или API). Он служит в качестве посредника между клиентом и сервером.

Поскольку API играет решающую роль во взаимодействии клиент–сервер, разрабатывать API всегда необходимо с учетом лучших практик. Это помогает разработчикам, поддерживающим их, а также их пользователям, не сталкиваться с проблемами при повседневной работе.

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

Для начала, что такое REST API?

REST означает передачу состояния представления (Representational State Transfer). Это программный архитектурный стиль, созданный Роем Филдингом в 2000 году в качестве руководства для разработки архитектуры веб.

Любой API (Application Programming Interface, прикладной программный интерфейс), который следует принципу проектирования REST, называется RESTful.

Проще говоря, REST API  —  это средство связи двух компьютеров по протоколу HTTP (протокол передачи гипертекста), аналогично тому, как взаимодействуют клиенты и серверы.

Лучшие практики проектирования REST API

1. Для отправки и получения данных пользуйтесь форматом JSON

В прошлом взаимодействие через API, как на прием, так и на передачу, шло в основном в формате XML и даже HTML. Но в наши дни JSON (объектная нотация JavaScript) в значительной степени стал форматом де-факто для отправки и получения данных по API.

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

JavaScript, например, содержит встроенный метод для расшифровки данных JSON через fetch API, потому что JSON был создан в первую очередь для работы с этим языком. Но если вы используете любой другой язык программирования, к примеру Python или PHP, теперь у всех них также есть методы для анализа и обработки JSON.

Например, Python предоставляет json.loads() и json.dumps() для работы с данными JSON.

Чтобы убедиться, что клиент правильно интерпретирует данные JSON, необходимо в заголовках ответа установить тип содержимого (Content-Type) на application/json при выполнении запроса.

С другой стороны, если говорить о серверных фреймворках, многие из них автоматически устанавливают Content-Type. Например, у Express для этого теперь есть промежуточное программное обеспечение express.json(). Пакет NPM body-parser по-прежнему работает для той же цели.

2.В эндпойнтах употребляйте глаголы, не существительные

Когда вы разрабатываете REST API, не стоит использовать глаголы в путях к конечным точкам (endpoints). В конечных точках должны использоваться существительные, обозначающие то, что делает каждый из них.

Это связано с тем, что HTTP-методы, такие как GET, POST, PUT, PATCH и DELETE, уже находятся в форме глагола для выполнения базовых операций CRUD (создание, чтение, обновление, удаление).

GET, POST, PUT, PATCH и DELETE  —  самые распространенные HTTP-глаголы. Есть и другие, такие как COPY, PURGE, LINK, UNLINK и так далее.

Так, например, эндпойнт не должен выглядеть следующим образом: https://mysite.com/getPosts или https://mysite.com/createPost

Вместо этого это должно быть что-то вроде: https://mysite.com/posts

Короче говоря, позвольте HTTP-глаголам обрабатывать то, что делают конечные точки. Таким образом, GET будет извлекать данные, POST создаст данные, PUT обновит данные, а DELETE избавит от данных.

3. Давайте имена наборам во множественном числе

Вы можете думать о данных вашего API как о наборе различных ресурсов от клиентов.

Если у вас есть какой-то эндпойнт вроде https://mysite.com/post/123, это может быть нормально для удаления записи с помощью запроса DELETE или обновления записи с помощью запроса PUT или PATCH, но это не говорит пользователю о том, что в коллекции могут быть какие-то другие записи. Вот почему в ваших коллекциях должны использоваться существительные во множественном числе.

Итак, вместо https://mysite.com/post/123 , это должно быть https://mysite.com/posts/123 .

4. Используйте коды состояния при обработке ошибок

Всегда применяйте стандартные коды состояния HTTP в ответах на запросы через ваш API. Это поможет пользователям определить, что происходит  —  прошел ли запрос успешно, произошел ли сбой или что-то еще.

Ниже приведена таблица, показывающая различные диапазоны кодов состояния HTTP и их значения:

5. Используйте вложенность в конечных точках для отображения взаимосвязей

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

Например, в случае многопользовательской платформы ведения блогов разные сообщения могут быть написаны разными авторами, поэтому конечная точка, такая как https://mysite.com/posts/author/, выглядит допустимой для реализации вложенности.

Аналогично, каждая запись в блоге может быть со своими отдельными комментариями, поэтому для получения комментариев имеет смысл конечная конечная точка вида https://mysite.com/posts/postId/comments.

Следует избегать вложенности глубиной более трех уровней, так как это может сделать API менее элегантным и читаемым.

6. Используйте фильтрацию, сортировку и разбивку на страницы для получения запрошенных данных

Иногда база данных API может быть невероятно большой. Если это произойдет, извлечение данных из такой базы данных может быть очень медленным.

Фильтрация, сортировка и разбивка на страницы  —  это все действия, которые можно выполнить с коллекцией REST API. Тогда ему остается только извлекать, сортировать и упорядочивать необходимые данные по страницам, чтобы сервер не был слишком занят запросами.

Пример отфильтрованной конечной точки приведен ниже:
https://mysite.com/posts?tags=javascript
Эта конечная точка будет извлекать любую запись, содержащую тег JavaScript.

7. Пользуйтесь SSL для обеспечения безопасности

SSL расшифровывается как “уровень защищенных сокетов” (secure socket layer). Эта технология имеет решающее значение в обеспечении безопасности при разработке REST API. Она сделает ваш API менее уязвимым для вредоносных атак.

Другие меры безопасности, которые вам надо принять во внимание, включают в себя: обеспечение конфиденциальной связи между сервером и клиентом и обеспечение того, чтобы любой, кто использует API, не получал больше того, что запрашивает.

SSL-сертификаты несложно загрузить на сервер, и они, как правило, доступны бесплатно в течение первого года. В противном случае, их недорого купить.

Явная разница между URL-адресом REST API, который работает через SSL, и тем, который этого не делает,  —  это буква “s” в HTTP:
https://mysite.com/posts работает по протоколу SSL.
http://mysite.com/posts не работает по протоколу SSL.

8. Соблюдайте прозрачность в управлении версиями

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

Одна из наиболее распространенных систем управления версиями в веб-разработке  —  семантическое управление версиями.

Пример семантического управления версиями: 1.0.0, 2.1.2 и 3.3.4. Первое число представляет основную версию (мажорную), второе число представляет минорную версию, а третье представляет версию исправления (патча).

Многие RESTful API от технологических гигантов и частных лиц обычно выглядят так:
https://mysite.com/v1  —  для версии 1
https://mysite.com/v2  —  для версии 2

Facebook обновляет свои API-интерфейсы вот таким образом:

Spotify выполняет управление версиями так же:

Это относится не ко всякому API. Mailchimp управляет версиями своего API иначе:

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

9. Предоставьте точную документацию по API

Когда вы создаете REST API, вам нужно помочь клиентам (потребителям) изучить его и понять, как правильно им пользоваться . Лучший способ для этого  —  предоставить хорошую документацию по API.

Документация должна содержать:

• соответствующие конечные точки API;
• примеры запросов;
• реализации конечных точек на нескольких языках программирования;
• сообщения для различных ошибок с их кодами состояния.

Один из наиболее распространенных инструментов для документации API  —  это Swagger. Также для документирования ваших API можно воспользоваться Postman, так как это очень популярный инструмент тестирования API при разработке программного обеспечения.

Заключение

Из этой статьи вы узнали о нескольких рекомендациях, которые следует учитывать при создании REST API.

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

Спасибо за чтение. А теперь вы можете воспользоваться описанным в реальности.

Читайте также:

• Пишем асинхронный неблокирующий Rest API на Java
• Создание REST-клиента с помощью Spring Cloud OpenFeign и Netflix Ribbon
• Как спроектировать REST API для выполнения системных команд с помощью Actix Rust

Читайте нас в Telegram, VK и Яндекс.Дзен

---

Перевод статьи: Kolade Chris, “REST API Best Practices — REST Endpoint Design Examples”