APIСтандартизация
тема 1 Открыть слайдами →

Часть 5 из 15 · слайды 34–36

Практика: контракт

Правил уже достаточно, чтобы спроектировать контракт Service Desk и найти ошибки в чужом.

  1. 34Сначала API — потом код
  2. 35Найдите нарушения самостоятельно
  3. 36Что мы уже собрали

34Сначала API — потом код

Для Service Desk фиксируем операции до того, как напишем первую строку реализации.

EndpointНазначениеУспех
GET /api/v1/ticketsсписок обращений200
POST /api/v1/ticketsсоздать обращение201
GET /api/v1/tickets/{ticket_id}одно обращение200
PATCH /api/v1/tickets/{ticket_id}изменить поля200
DELETE /api/v1/tickets/{ticket_id}удалить204

Для каждого endpoint определите:

  • request: параметры и тело;
  • success response;
  • error responses;
  • authentication.
После работы → как это решено в учебном проекте
EndpointОшибкиТокен
GET /tickets422нет
POST /tickets401, 403, 422да
GET /tickets/{id}404, 422нет
PATCH /tickets/{id}401, 403, 404, 422да
DELETE /tickets/{id}401, 403, 404, 422да

35Найдите нарушения самостоятельно

Перед вами контракт другой команды. Сначала найдите нарушения сами, затем запустите проверку правилами.

Необходимо определить:

  • где действие помещено в URI;
  • где неверно выбран HTTP method;
  • где identifier логичнее сделать path parameter;
  • где контракт непоследователен.

Проверка использует те же имена правил, что и .spectral.yaml учебного проекта, и печатает результат в формате Spectral. Текст можно исправлять и проверять снова.

contract.txtметод и путь, по одному на строку

36Что мы уже собрали

Теперь у нас есть вся цепочка обмена между клиентом и сервером.

  1. CLIENT
  2. HTTP REQUEST
  3. RESOURCE URI + HTTP METHOD
  4. SERVER
  5. HTTP STATUS + HEADERS + JSON
  6. CLIENT

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

Следующая проблема — как формально описать этот контракт.

Кадр крупным планом