Как читать документацию API
↑ 1.6 Документация API: Swagger и OpenAPI · → Следующая
Зачем это аналитику и PM
Пока в задаче нет метода, адреса и кода ошибки, разработка додумывает контракт. Документация — место, где это уже должно быть написано, и её читают до того, как открывать клиент.
План темы
- что искать в первую очередь
- пример запроса и ответа
- коды ошибок
- лимиты и версии
Объяснение
Документация API — договор: какой запрос сервис принимает и что считает ответом. Страница может быть красивой и при этом молчать про обязательное поле. Читают не «всё подряд», а ответ на текущий вопрос.
Как меню в столовой. Сначала окно выдачи и чем платить, потом одно блюдо, потом что будет, если блюда нет. Не начинают с истории кухни.
С чего начать
Найдите адрес стенда и способ допуска. Без них пример некуда отправить. Дальше один метод: имя действия, путь, что лежит в пути, что в query, что в теле. Отметьте поля, без которых сервис отвечает отказом. Пример успешного тела сверьте с этими полями: в примере не должно быть сюрприза, которого нет в списке.
Коды читают рядом с методом, не в общем приложении в конце, если у метода свой список. Минимум два: успех и самый частый отказ. Лимиты — сколько вызовов за промежуток времени и что будет при превышении. Версия — та, что обещана клиентам сейчас. Номер в адресе и номер в шапке документа могут расходиться: запишите оба и спросите, какой считает команда.
Учебный Petstore, который прилагают к Swagger, годится, чтобы увидеть форму страницы. Адрес берите из документации проекта, в эту заметку хост не копируют.
Примеры
Карточка метода, которую можно перенести в задачу:
GET /orders/{orderId}
Стенд: из servers выбранного файла, не из памяти.
Допуск: как в разделе security, без вставки живого ключа.
Успех: 200 и объект заказа.
Нет заказа: 404.
Лимит: смотреть в описании сервиса, не выдумывать число.Нюансы и подводные камни
- Пример года назад и список полей сегодня. Верит список, если страница собрана из спецификации. Иначе спросите дату.
- Код
200с текстом ошибки внутри тела. Для задачи важен признак, которым пользуется клиент. - «Без лимита» в старой статье не отменяет лимит на шлюзе. Ищите его у владельца сервиса.
- Чужой ключ из публичного примера не тащат в свой стенд.
Практика
Возьмите один публичный метод: Petstore по адресу из документации проекта или спецификацию вашей команды. Заполните карточку выше своими словами.
Ожидаемый результат: у метода есть путь, место допуска, один код успеха, один отказ и пометка, где лежит лимит или что его в тексте нет. Живого секрета в карточке нет.
Вопросы с ответами
Что открывать первым?
Адрес стенда, допуск и один нужный метод. Общее введение не заменяет путь и поля.
Пример важнее списка полей?
Нет. Пример показывает удачный случай. Список говорит, без чего запрос не примут. Если они спорят, это вопрос к автору, а не повод выбрать наугад.
Где искать лимит?
В описании сервиса, у шлюза или в разделе квот. Число из чужого конспекта не подставляют.
Зачем отдельно писать версию?
Клиент может говорить со старым контрактом. Номер в задаче фиксирует, какой текст вы читали.