Post #321

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 раньше не слышал.