Что писать в спецификации при проектировании REST-API?

Всем привет!
Хотелось написать 10 постов про REST, но решил, что лучшее - враг хорошего. Поэтому пишу про:
- что должно быть в спецификации
- чек - листы проверки
- шаблоны проектирования
- проблемы REST, о которых молчат
- причины срочно учить другие интеграции

💬Если захочется что-то узнать подробнее- пиши в комментариях

К делу!

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

1️⃣Ресурс и конечные точки
При проектировании конечных точек(end points) ресурса используйте имена существительные во множественном числе, использовать глаголы не рекомендуется. Для разграничения действий с ресурсами на уровне HTTP-запроса были придуманы следующие варианты:
➖GET - получение ресурса
➖POST - создание ресурса
➖PUT/PATCH - обновление ресурса
➖DELETE удаление - ресурса

Они соответствуют CRUD (Create, Read, Update, Delete)

Примеры:
- GET /books для получения списка книг, а не GET /get-books или GET /book
- GET /books{id} для получения конкретной книги
- POST /books - для добавления новой книги
- PUT /books/{id} - для модификации полных данных книги с заданным идентификатором (id)
- PATCH /books/{id} обновляет частичные изменения в книге
- DELETE /books/{id} удалениt книги по id
2️⃣Формат отправки и получения данных
JSON и тока❗️
3⃣Используйте коды состояний
➖1хх – Информационный код
➖2хх – успешный ответ
➖3хх – перенаправление
➖4хх – ошибка на стороне клиента
➖5хх – ошибка сервера

4⃣Стандартизируйте ответы
Сделайте так, чтобы каждый метод возвращал стандартные ошибки и стандартные ответы, если GET /books{id} возвращает

{
     bookId: 1,
     name: "Я, Робот"
  }

То GET /books возвращает

  {
     bookId: 1,
     name: " Я, Робот "
  },
  {
     bookId: 2,
     name: "Академия"
  }
POST в свою очередь после создания объекта вернет 
{
     "bookId": 3,
     "name": "Вторая Академия"
 }

Не используйте универсальные сообщения, например, «Книга успешно создана», это понятно из кода состояния HTTP.
Пример:

{
  "code": "book/not_found",
  "message": "Книга с ID 6 не найдена"
}

5⃣Параметры
➖Headers – обычно включает авторизацию и техническую информацию
➖Path параметры – Передаются в пути запроса, идут перед знаком «?» в описании обозначают фигурными скобками GET /books/{id}
➖Query параметры – передаются после знака «?» с указанием имени и значением, несколько параметров соединяются знаком «&» GET /books?author=Азимов&typePublication=audio
➖Body – Обычно включает JSON со всеми атрибутами необходимыми для запроса

Не забываем для всех параметров и атрибутов указывать:
➖тип
➖длину
➖обязательность
➖кодировку
➖маску
➖пример
Маппинг данных для фронта и бэка, если это применимо в вашем случае.
6⃣Используйте разбиение на страницы, фильтрацию и сортировку при выборе коллекций записей
После проектирования end points, возвращающего массив (или список) элементов(объектов), сразу задумайтесь о необходимости разбиения на страницы(пагинацию).
Практика показывает, что со временем данные в БД растут, поэтому важно на уровне проектирования предусмотреть возврат конечного числа объектов. Пагинация позволит вам повысить скорость загрузки данных и снизить требования пропускной способности канала. ну и в целом, пользователям удобнее работать с 10-ю записями на экране.
Подумайте о пользователях и спроектируйте фильтры, а также правила сортировки полей, для которых она нужна.
При проектировании API эти свойства разбиения на страницы, фильтрации и сортировки определяются как параметры запроса в URL-адресе. Например, если вы хотим получить информацию о первых 10 книгах, принадлежащих к категории «роман», то наша конечная точка будет выглядеть вот так:
GET /books?limit=10&category=romance
7⃣PATCH и PUT
Соберите фронтов и беков, спросите, как будете делать на проекте и через 3 часа зафиксируйте договоренность, если так быстро команда не договорится, сводите их в пятницу в бар, а в понедельник задайте вопрос ещё раз.
8⃣Кэширование
Чтобы повысить производительность нашего API, полезно следить за данными, которые редко меняются и к которым часто обращаются. Для таких данных мы можем рассмотреть возможность использования кэширования.
Использование кэшированных данных будет полезным для пользователей для загрузки конфигураций и каталогов информации, которые не предназначены для постоянного изменения в течение долгого времени. При использовании кэширования не забудьте включить Cache-Control в заголовки. Это поможет пользователям эффективно использовать систему кэширования.
9⃣Используйте даты в формате UTC
Частая ошибка начать использовать локальное время и столкнуться с гигантскими проблемами при выходе в другой часовой пояс, сразу используйте ISO 8601 и не наступайте на эти грабли.

Кстати! Сегодня на митапе в 18:30 Аня Мозер расскажет еще больше про REST API приходи

С вами был @CrazyElephant