Postman, кроме того, что производит инструмент для тестирования API, ещё собирает лучшие практики проектирования.
Для этого у них есть отдельная команда Postman Open Technologies, которая также собирает информацию о стандартах, отраслевых форматах и спецификациях, открытых API.
Каталог практик и паттернов оформлен как рабочее пространство Postman: https://www.postman.com/postman/workspace/postman-open-technologies-openapi-governance-templates/overview (открывается прямо в Postman!)
Смысл каталога в том, чтобы не придумывать каждый раз "как мы будем возвращать сумму платежа" или "как будем делать пагинацию", а брать готовое решение.
На текущий момент там описаны следующие паттерны:
🔸 Форматы данных:
🔹Коды стран (ISO 3166)
🔹Коды валют (ISO 4217)
🔹Дата, время и временные промежутки (ISO 8601)
🔹Числа с десятичными дробями
🔹Кастомные заголовки HTTP
🔹Расширенное описание ошибки (RFC 9457 - кстати, очень хороший формат для передачи смысла ошибки HTTP)
🔸Управление кэшированием:
🔹Параметр Cache-control
🔹Параметр Etag
🔹Параметр Expires
🔸Фильтрация:
🔹Параметры поискового запроса
🔹Точное соответствие
🔹Диапазон значений поля
🔹Выбор полей для ответа
🔸Пагинация:
🔹Заголовки page and per_page (rfc 5988)
🔹Курсор / NextRecordKey
🔹Параметры Limit и Offset
🔸Сортировка:
🔹По одному полю - параметры sort_by, sort_order
🔹По нескольким полям
🔸Версионирование:
🔹На уровне URL API
🔹На уровне отдельного ресурса
🔹Через заголовок Accept-Version
🔹Через заголовок Accept
🔸Информация:
🔹Контакты разработчиков
🔹Лицензия
🔹Условия использования
🔹Заголовок Sunset (предупреждение, что ресурс станет недоступным в определенное время)
Набор паттернов интересный, я, например, про RFC 9457, версионирование на уровне ресурсов и Sunset header раньше не слышал.
Для этого у них есть отдельная команда Postman Open Technologies, которая также собирает информацию о стандартах, отраслевых форматах и спецификациях, открытых API.
Каталог практик и паттернов оформлен как рабочее пространство Postman: https://www.postman.com/postman/workspace/postman-open-technologies-openapi-governance-templates/overview (открывается прямо в Postman!)
Смысл каталога в том, чтобы не придумывать каждый раз "как мы будем возвращать сумму платежа" или "как будем делать пагинацию", а брать готовое решение.
На текущий момент там описаны следующие паттерны:
🔸 Форматы данных:
🔹Коды стран (ISO 3166)
🔹Коды валют (ISO 4217)
🔹Дата, время и временные промежутки (ISO 8601)
🔹Числа с десятичными дробями
🔹Кастомные заголовки HTTP
🔹Расширенное описание ошибки (RFC 9457 - кстати, очень хороший формат для передачи смысла ошибки HTTP)
🔸Управление кэшированием:
🔹Параметр Cache-control
🔹Параметр Etag
🔹Параметр Expires
🔸Фильтрация:
🔹Параметры поискового запроса
🔹Точное соответствие
🔹Диапазон значений поля
🔹Выбор полей для ответа
🔸Пагинация:
🔹Заголовки page and per_page (rfc 5988)
🔹Курсор / NextRecordKey
🔹Параметры Limit и Offset
🔸Сортировка:
🔹По одному полю - параметры sort_by, sort_order
🔹По нескольким полям
🔸Версионирование:
🔹На уровне URL API
🔹На уровне отдельного ресурса
🔹Через заголовок Accept-Version
🔹Через заголовок Accept
🔸Информация:
🔹Контакты разработчиков
🔹Лицензия
🔹Условия использования
🔹Заголовок Sunset (предупреждение, что ресурс станет недоступным в определенное время)
Набор паттернов интересный, я, например, про RFC 9457, версионирование на уровне ресурсов и Sunset header раньше не слышал.