Принципы построения синхронного API

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

Уровень 0
Легаси

Единственный URI и HTTP метод (как правило POST) и использование XML.

Уровень 1
Ресурсы

Каждому ресурсу отдельный эндпоинт, можно и на JSON перейти.

Уровень 2
HTTP-глаголы

Используем правильные HTTP методы, статус коды, поддерживаем фильтрацию, пагинацию, поиск, сортировку и версионирование.

Наша стратегия достигнуть 2 уровня на всех канонических API.

Построение URI

https:// api.leroymerlin.ru / domain / application / v1 / products?siteId=12&statusCode=active
\_____/\___________________/\_______/\____________/\___/\_________/\___________________________/
 схема        хост            домен      система  версия  ресурс     параметры запроса
                                          

Используй kebab-case для URL-ов и camelCase для параметров и аттрибутов.

  • У каждого ресурса свой эндпоинт.
  • Название ресурса всегда в множественном числе.
  • Если ресурс относится к другому, используй вложенность.
  • Максимальная вложенность — 1.
  • Допускается использование единственного числа там, где других таких же предметов быть не может

Умеренная гранулярность.

Не надо возвращать информацию, которую не спрашивали.

Используй Суррогатные ключи правильно.

Суррогатный ключ — это ключ, искуственно сгенерированый системой. Не надо путать суррогатный ключ с первичным ключом базы данных. Ещё бывают натуральные ключи, сформированные из атрибутов, существующих в реальной жизни.

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

HTTP-методы

  • GET получить
  • POST создать
  • PUT перезаписать
  • PATCH частично обновить
  • DELETE удалить
  • OPTIONS вернуть все HTTP-методы, доступные для эндпоинта

Когда что-то не подходит

  • используй POST метод
  • используй action глаголы
  • воспользуйся паттерном /collections/{resource}:{action}

URL параметры запросов

Заголовки

Содержит технические параметры или элементы контекста.

Content-Type: application/json
ADEO-BU-CODE: 10

Path параметры

Эти параметры — часть URL. С их помощью можно понять, к какому ресурсу мы обращаемся.

Query параметры

Позволяют фильтровать и сортировать запросы.

Пагинация

  • Пагинация по номеру страницы.
  • Пагинация по курсору.Не стоит хранить курсоры: они быстро становятся невалидными из-за вставки или удаления элементов.
  • Пагинация через оффсет & лимит.
  • Пагинация через временные метки.В качестве ключа для пагинации по временным меткам используется Unix timestamp.

Ответ: Общие правила

  • Структура ответа HTTP не должна зависеть от структуры БД
  • Все поля должны быть понятны с бизнес точки зрения
  • Все наименования полей должны быть простыми, интуитивными и согласованными
  • Стоит избегать использование технических терминов и специфических терминов систем

Ответ: Статус коды

Все методы

  • Для всех эндпоинтов необходимо возвращать статус коды.
  • Каждый сервис потенциально должен уметь возвращать 500-ки.
  • Каждый сервис, требующий как минимум один обязательный параметр на вход, должен уметь возвращать 400-ки с описанием ошибки.
  • Каждый секьюрный сервис должен уметь возвращать 401 ошибку.

GET

  • Каждый сервис в случае отсутствия данных должен возвращать 404.
  • Каждая коллекция обязана вернуть 200, если возвращается полностью.
  • Каждая коллекция должна вернуть 206, если возвращается частично.

POST

  • Верни 201 после создания ресурса.

PUT & PATCH:

  • Верни 200 после обновления ресурса.

DELETE

  • Верни 204 после успешно удалённой информации.

Ответ: Коды ошибок

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

Один из популярных форматов описания ошибок JSON-API:

{
  "errors": [{
    "code": "ERR-01234",
    "title": "OAuth Exception",
    "details": "Session has expired at unix time 1385243766.", 
    "links": {
      "about": "http://example.com/docs/errors/#ERR-01234"
    }
  }]
}

Или вот кусок кода в формате Сваггера с описанием кода ответа и кода ошибок:

{ 
  Responses:
    ”200”:
      description: mySuccessResponse
  Schema:
    type: array
  Items:
    $ref: “#/definitions/Pet”,
    “400”: 
      description: Invalid status value
}

Ответы: Формат данных

E.164 – Телефонный номер

[+][код страны][код местности][местный номер]

  • + знак плюса
  • код страны международный код страны
  • код местности код местности без 0 в начале
  • местный номер местный номер телефона

ISO 639 – Язык

  • eng – Английский
  • fra – Французский
  • rus – Русский

ISO 3166-1 — Язык

  • Russia (Russian Federation) Россия RU RUS 643
  • France Франция FR FRA 250
  • China Китай CN CHN 156

ISO 8601 – Дата

  • YYYY-MM 2020-06
  • YYYYMMDD 20200602
  • YYYY-MM-DDThh:mm:ss±hh 2020-06-02T15:22:00+00:00

ISO 4217 — Деньги

  • EUR 978 – Евро
  • USD 840 – Доллар США
  • KZT 398 – Тенге
  • BYN 933 – Беларусский Рубль

UCUM – Меры измерения

Все меры измерения ищите в UCUM specification.

Последнее изменение 17.11.2020: Update sync.md (#20) (d01ffc5)