Простой CRUD REST API можно быстро создать, но есть несколько ошибок, на которые следует обратить внимание.

1. У вас нет REST API

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

Основная идея - отделить переднюю часть от задней. Создание REST API - лишь один из способов сделать это. Есть и другие варианты, такие как GraphQL API, SOAP API или использование BaaS-провайдера. Какой из них выбрать, будет зависеть от времени, бюджета, стека технологий и знаний.

2. Вы не контролируете версию своего API.

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

GET /v1/lists

А затем создайте:

GET /v2/lists

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

3. У вас есть вложенные ресурсы

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

GET /v1/lists
GET /v1/lists/1/tasks
GET /v1/lists/1/tasks/1

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

Плоский API, например:

GET /v1/lists
GET /v1/tasks?list_id=1
GET /v1/tasks?task_id=1

позволит вам делать то же самое и многое другое (если вы поддерживаете фильтрацию).

4. Вы неправильно фильтруете

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

GET /v1/lists

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

Вы должны только автоматически отфильтровывать ресурсы, которые пользователь никогда не должен видеть. Затем добавьте параметры фильтрации, чтобы пользовательский интерфейс мог выбирать, что отфильтровать. Предполагая, что идентификатор текущего пользователя равен 1, внешний интерфейс может вызвать:

GET /v1/lists?owner=1

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

GET /v1/lists

чтобы получить все списки задач.

5. Вы не разбиваете результаты на страницы

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

Пагинация на основе смещения - это распространенный подход к реализации нумерации страниц. Например:

GET /v1/tasks?offset=20&limit=10

пропустит первые 20 задач и вернет только 10 задач. Если вы хотите поддерживать переход на определенную страницу, вам также нужно будет вернуть общее количество записей, чтобы внешний интерфейс мог определить, сколько номеров страниц показывать.

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

6. У вас плохая документация

Если вы ожидаете, что другие будут использовать ваш API, вам необходимо предоставить актуальную документацию. Устаревшая или несуществующая документация затруднит понимание тем, на что способен ваш API, для тех, кто не знаком с исходной кодовой базой. В идеале ваш API должен быть задокументирован со спецификацией OpenAPI (ранее известной как Swagger), а документация должна соответствовать вашему коду.

OpenAPI - популярный стандарт для документирования REST API с помощью файла JSON или YAML. С помощью спецификации вы можете задокументировать, какие конечные точки доступны, какие параметры принимает каждая конечная точка и что она возвращает. Существуют также средства визуализации, которые придают вашей документации приятный интерфейс. Swagger UI и ReDoc - два популярных.

Некоторые фреймворки и библиотеки позволяют писать документацию прямо вместе с кодом и генерировать OpenAPI JSON или YAML. Встроенная документация - лучший подход, потому что она с меньшей вероятностью устареет.

Ключевые выводы

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

  1. Иметь API
  2. Версия вашего API
  3. Нет вложенных ресурсов
  4. Поддержка фильтрации
  5. Поддержка разбивки на страницы
  6. Задокументируйте свой API

Вы уже этим занимаетесь? Есть ли еще какие-то аспекты, которые вас укусили? Позвольте мне знать в комментариях ниже!