Шаг 3 "Параметры (Описание API)"

Параметрами являются опции, которые можно передать конечной точке (например, указать формат ответа или возвращаемую сумму), чтобы повлиять на ответ. Существует четыре типа параметров:

• параметры заголовка,
• параметры path,
• параметры строки запроса,
• параметры тела запроса.

Различные типы параметров часто документируются в отдельных группах на одной странице. Не все конечные точки могут содержать каждый тип параметра.

Примеры параметров

Скриншот ниже является примером раздела параметров с Box API:

В этом примере параметры сгруппированы по типу:

• параметры path,
• параметры запроса,
• параметры тела.

Конечная точка также выделяет параметр path collab_id распознаваемым образом в определении конечной точки.

Часто параметры просто перечислены в таблице или списке определений, как в этом примере:

Вот пример документации API Yelp

Можно форматировать значения различными способами, кроме таблицы. При использовании списка определений или другого не табличного формата, обязательно нужно разработать стили, которые сделают значения легко читаемыми.

Четыре типа параметров

REST API обладают 4 типами параметров:

• Параметры заголовка: параметры, включенные в заголовок запроса, обычно относятся к авторизации.
• Параметры path: Параметры в пределах path конечной точки перед строкой запроса, отделяются знаком ?. Обычно эти параметры выделяются фигурными скобками.
• Параметры строки запроса: Параметры в строке запроса конечной точки, располагаются после знака ?.
• Параметры тела запроса: Параметры, включенные в тело запроса. Обычно в формате JSON.

Что следует отметить в документировании параметров

Независимо от типа параметра, определите следующее для каждого параметра:

Типы данных параметров

Максимальное и минимальное значения параметров

Типы данных параметров

API могут некорректно обрабатывать параметр, если он имеет неправильный тип данных или неправильный формат. Перечисление типа данных является хорошей идеей для всех типов параметров, но особенно важно для параметров тела запроса, поскольку они обычно форматируются в JSON.

Вот типы данных наиболее распространенные в REST API:

• string: буквенно-цифровая последовательность букв и / или цифр;
• integer: целое число - может быть положительным или отрицательным;
• boolean: true или false значение;
• object: пара ключ-значение в формате JSON
• array: массив значений

Максимальное и минимальное значения параметров

Помимо указания типа данных, параметры должны указывать максимальные, минимальные и допустимые значения. Например, если API сервиса погоды допускает только координаты долготы и широты конкретных стран, эти ограничения должны быть описаны в документации в разделе параметров.

Пропуск информации о максимальных / минимальных значениях или других недопустимых значениях является распространенной ошибкой в ​​документации. Разработчики часто не осознают всех «творческих» способов, которыми пользователи могут использовать API. Команда тестирования или обеспечения качества (QA), вероятно, является лучшим ресурсом для определения значений, которые не должны допускаться, потому что задача QA - попытаться взломать API.

Параметры заголовка

Параметры заголовка включаются в заголовок запроса. Обычно заголовок включает в себя только параметры авторизации, которые являются общими для всех конечных точек; в результате параметры заголовка обычно не документируются для каждой конечной точке. Детали авторизации в параметрах заголовка документированы в разделе Аутентификация и авторизация.

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

Параметры path

Параметры path являются частью конечной точки. Например, в следующей конечной точке {user} и {bikeId} являются обязательными параметрами path:

/service/myresource/user/{user}/bicycles/{bicycleId}

Параметры path обычно устанавливаются с помощью фигурных скобок. Но в некоторых API документациях стили прописывают перед значением двоеточие или используют вообще иной синтаксис. При документировании параметров path указываются значения по умолчанию, допустимые значения и другие сведения.

Цветовая кодировка параметра path

При перечислении параметров path в конечной точке, может помочь цветовое кодирование параметров, для их легкой идентификации. Цветовое выделение параметров дает понять, что является параметром path, а что нет. Посредством цвета мы создаем непосредственную связь между конечной точкой и определениями параметров.

Например, если выделить цветом параметры {user} и {bicycleId} в конечной точке:

/service/myresource/user/{user}/bicycles/{bicycleId}

То позже можно использовать этот же цвет при описании этих же параметров.

Использование цвета для выделения параметров позволяет легко выделить определяемый параметр и его связь с определением конечной точки.

Параметры строки запроса

Параметры строки запроса указываются после знака вопроса ? В конечной точке. Знак вопроса, параметры, которые следуют за ним и их значения, называется «строкой запроса». В строке запроса каждый параметр перечисляется один за другим с амперсандом &, разделяющим их. Порядок параметров строки запроса не имеет значения.

Эта строка запроса:

/surfreport/{beachId}?days=3&units=metric&time=1400

или эта

/surfreport/{beachId}?time=1400&units=metric&days=3

вернут один и тот же результат.

Однако в параметрах path порядок имеет значение. Если параметр является частью фактической конечной точки (не добавляется после строки запроса), это значение обычно описывается в описании самой конечной точки.

Параметры тела запроса

Часто с запросами POST (где мы что-то создаем) мы отправляем объект JSON в теле запроса. Этот параметр и есть тело запроса. Обычно форматом тела запроса является JSON. Этот JSON объект может быть длинным списком пар ключ-значение с несколькими уровнями вложенности.

Например, конечной точкой может быть что-то простое, например /surfreport/{beachId}. Но в тело запроса мы можем включить объект JSON со многими парами ключ-значение, например:

{
  "days": 2,
  "units": "imperial",
  "time": 1433524597
}

Документирование параметров тела сложного запроса

Документирование данных JSON (как в параметрах тела запроса, так и в ответах) является одной из самых сложных частей документации API. Документирование JSON объекта будет легким, если этот объект прост, с несколькими парами ключ-значение на одном уровне. Но если у нас есть JSON объект с несколькими объектами внутри объектов, множественными уровнями вложенности и большими объемными данными, это может быть сложно. И если объект JSON занимает более 100 строк, или 1000, нам необходимо тщательно продумать, как представить информацию.

Таблицы хороши для документирования JSON, но в них трудно различать элементы верхнего уровня и подуровня. Объект, который содержит объект, который также содержит объект, и другой объект и т. Д., Может сбивать с толку.

Безусловно, если объект JSON относительно мал, таблица, вероятно, является лучшим вариантом. Но есть и другие дизайнерские подходы.

Взгляните на ресурс eBay findItemsByProduct. Вот параметр тела запроса (в данном случае формат XML):

Ниже параметра тела запроса находится таблица, которая описывает каждый параметр:

Но пример запроса также содержит ссылки на каждый из параметров. При клике на значение параметра в примере запроса, мы переходим на страницу, которая предоставляет более подробную информацию о значении этого параметра, например ItemFilter. Отдельная страница с более подробной информацией лучше и удобнее, потому что значения параметров являются более сложными и требуют подробного объяснения.

Те же значения параметров могут использоваться и в других запросах, поэтому подход eBay, вероятно, облегчает повторное использование. Тем не менее, кому-то может не нравиться прыгать на другие страницы для получения необходимой информации.

Подход Swagger к параметрам тела запроса

Пользовательский интерфейс Swagger, который мы рассмотрим позже, а также его демо, предоставляет другой подход к документированию параметра тела запроса. Swagger UI показывает параметры тела запроса в формате, который вы видите ниже. Интерфейс Swagger позволяет переключаться между представлением «Пример значения» и представлением «Модель» для ответов и параметров тела запроса.

Посмотрим на Swagger Petstore для изучения. “Пример значения” показывает образец синтаксиса вместе с примерами. При нажатии на ссылку “Модель””, видим пример параметра тела запроса и описания каждого элемента.

Модель включает в себя переключатели «развернуть / свернуть» со значениями. (Демо Petstore не имеет множество описаний параметров в модели, но если включить описания, они будут отображаться в модели, а не в примере значения.)

Можно заметить, что существует множество вариантов документирования JSON и XML в параметрах тела запроса. Правильного способа документировать информацию нет. Как всегда, выбираем метод, который отображает параметры нашего API наиболее простым и легким для чтения способом.

Если у нас относительно простые параметры, наш выбор не будет иметь большого значения. Но если сложные, громоздкие параметры, то, возможно, придется прибегнуть к пользовательским стилям и шаблонам, чтобы представить их более четко. Исследуем эту тему более подробно в разделе Пример и схема ответа.

Параметры конечной точки SurfReport

Давайте посмотрим доступные параметры и создадим таблицу с описанием параметров для нашего нового ресурса surfreport. Вот пример, как может выглядеть информация о параметрах:

Параметры

Параметры path

Параметры строки запроса

Следующие шаги

После того, как мы задокументировали параметры пора посмотреть на Пример запроса к ресурсу

🔙

Go next ➡