Подходы к проектированию

• Дизайн API от потребностей продукта
• Простота и удобство использования API потребителем важнее простоты и удобства реализации поставщиком
• TODO Сергей Константинов. API
  • метод (сигнатура)
    • Стремитесь к тому, чтобы из сигнатуры функции было абсолютно ясно, что она делает, что принимает на вход и что возвращает. Вообще, при прочтении кода, работающего с вашим API, должно быть сразу понятно, что, собственно, он делает - без подглядывания в документацию.
    • Избегайте неявных частичных обновлений
    • Рекомендации по наименованию физических ресурсов, свойств
    • Конечные точки в URL – имя существительное, не глагол, Множественное число. Примеры:
      • https://{domain}/{service}/v1/customers/1
      • https://{domain}/{service}/{version}/{resourcepath}?fields={fieldId,*}
      • https://{domain}/files/v3/documents/ab34de
  • свойства метода (контракт\интерфейс)
    • Указывайте использованные стандарты
    • При этом существует «золотое правило», применимое не только к API, но ко множеству других областей проектирования: человек комфортно удерживает в краткосрочной памяти 7±2 различных объекта. Манипулировать большим числом сущностей человеку уже сложно. Это правило также известно как «закон Миллера». Бороться с этим законом можно только одним способом: декомпозицией. На каждом уровне работы с вашим API нужно стремиться логически группировать сущности под одним именем там, где это возможно и таким образом, чтобы разработчику никогда не приходилось оперировать более чем 10 сущностями одновременно. Должны выделить в структуре информационные домены: какие поля логически относятся к одной предметной области.
    • Сущности должны именоваться конкретно
    • Тип поля должен быть ясен из его названия
  • Возможные ошибки
    • Должны быть информативными
    • Рекомендуется применить смешанный подход
      • использовать HTTP Status Code согласно его семантике для индикации рода ошибки
      • вложенные (мета)данные в специально разработанном формате для детализации (RFC 7807 Problem Details for HTTP APIs)
        • Ошибка – уникальный идентификатор ошибки (буквенный код, число) в рамках ИС или модуля ИC
        • Сообщение – краткое сообщение, понятное человеку
        • Detail — более подробное объяснение ошибки
  • Примеры запроса\ответа успешные\ошибки

Качества хорошего API

Критерии качественного API

• API должен решать задачи максимально удобно и понятно
• Закладывание перспектив «на будущее» имеет смысл, только если это будущее у API есть, иначе это попросту оверинжиниринг.
• интерфейс API - один сценарий использования (SRP)
• очевидность
• читабельность
• консистентен: при разработке новой функциональности, т.е. при обращении к каким-то незнакомым сущностям в API, разработчик может действовать по аналогии с уже известными ему концепциями API, и его код будет работать.