5 "Пример и схема ответа (Описание API)"

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

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

Примеры и схемы ответов

Ниже приведен пример ответа от SendGrid API. Их документация обеспечивает отображение Примера на одной вкладке:

А схема ответа на другой вкладке:

Определение ответа называется схемой или моделью (термины используются как синонимы) и равняется на язык и описания схемы JSON. Что особенно хорошо в примере SendGrid, так это использование тегов раскрытия / свертывания для отражения той же структуры, что и в примере, с объектами на разных уровнях.

Swagger UI также предоставляет и пример значения и схему/модель. Например, в примере документа API Sunrise и Sunset Times, который используется в практике SwaggerUI (которое будет приведено позже в курсе), можно увидеть различие между примером ответа и схемой ответа. Вот Пример значения:

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

Схема ответа содержит все возможные свойства, возвращаемые в ответе. Вот почему нужен и пример ответа, и схема ответа. Вот схема ответа для API Sunrise и Sunset Times:

Схема или модель обеспечивает следующее:

• Описание каждого свойства;
• Определение типа данных для каждого свойства;
• Является ли каждое свойство обязательным или необязательным.

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

Нужно ли определять ответ?

Иногда в документации API схема ответа может отсутствовать, поскольку ответы могут показаться самоочевидными или интуитивно понятными. В API Twitter ответы не поясняются (пример здесь).

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

Использование реалистичных значений в примере ответа

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

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

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

Используйте правильный формат JSON для ответа. Такие инструменты, как JSON Formatter and Validator, помогут скорректировать синтаксис.

Если есть возможность добавить подсветку синтаксиса, обязательно нужно делать это. При использовании статического генератора сайтов, например Jekyll или синтаксис Markdown с GitHub, можно использовать встроенную подсветку синтаксиса Rouge. Другие статические генераторы сайтов могут использовать Pygments или аналогичные расширения.

Rouge и Pygments полагаются на «лексеры», чтобы указать, как код должен быть выделен. Например, некоторыми распространенными лексерами являются java, json, html, xml, cpp, dotnet и javascript.

Стратегии документирования вложенных объектов

Часто бывает, ответ содержит вложенные объекты (объекты внутри объектов) или повторяющиеся элементы. Форматирование документации для схемы ответа является одним из наиболее сложных аспектов справочной документации API.

Очень популярно использование таблиц. В курсе Петера Грюнбаума по технической документацииAPI для Udemy Грюнбаум представляет вложенные объекты, используя таблицы с различными столбцами:

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

Dropbox API представляет вложение косой чертой. Например, name_details/, team/ и quota_info указывают несколько уровней объекта.

Другие API будут вкладывать определения ответов для имитации структуры JSON. Вот пример из bit.ly API:

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

Подход eBay еще уникальнее. В их случае MinimumAdvertisedPrice вложен в DiscountPriceInfo, который вложен в Item, который вложен в ItemArray. (Обратите внимание, что этот ответ находится в формате XML вместо JSON.):

Вот документация ответа:

Также интересно, сколько деталей eBay включает для каждого элемента. В то время как авторы Twitter, опускают описания, авторы eBay пишут небольшие романы, описывающие каждый элемент в ответе.

Дизайн в три колонки

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

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

Многие API смоделировали свой дизайн после Stripe. Например, Slate, Spectacle или Readme.io. Следует ли использовать Дизайн в три колонки с документацией по API? Может быть.

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

MYOB Developer Center использует интересный подход к документированию JSON в своих API. Они перечисляют структуру JSON в виде таблицы, с разными уровнями отступов. Можно навести курсор мыши на поле с для появления всплывающей подсказки с описанием или щелкнуть по полю, чтобы раскрыть описание ниже. Использование всплывающих подсказок позволяет идеально выровнять строки, содержащие пример и описание.

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

Встраивание динамических ответов

Иногда ответы генерируются динамически на основе вызовов API в тестовой системе. Например, посмотрите на API Rhapsody и щелкните конечную точку - ответ генерируется динамически.

Другой API с динамическими ответами - это API OpenWeatherMap (с которым мы практиковались ранее). Если щелкнуть ссылку в разделе «Примеры вызовов API», например http://samples.openweathermap.org/data/2.5/weather?q=London, вы увидите ответ, возвращенный в браузере.

На самом деле, ответ OpenWeatherMap не генерируется динамически, но он так выглядит.

API Citygrid, который мы рассмотрели в разделе Пример запроса, также динамически генерирует ответы.

Такой динамический подход хорошо подходит для запросов GET, которые возвращают публичную информацию. Однако, вероятно, он не будет масштабироваться для других методов (таких как POST или DELETE) или для запроса авторизации.

Что насчет кодов ошибок?

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

Пример и схема ответа конечной точки SurfReport

Давайте создадим раздел для нашей конечной точки surfreport/{beachId} , в котором покажем пример и схему ответа.

Вот пример к разделу:

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

Ниже пример ответа конечной точки surfreport/{beachId}

{
    "surfreport": [
        {
            "beach": "Santa Cruz",
            "monday": {
                "1pm": {
                    "tide": 5,
                    "wind": 15,
                    "watertemp": 80,
                    "surfheight": 5,
                    "recommendation": "Go surfing!"
                },
                "2pm": {
                    "tide": -1,
                    "wind": 1,
                    "watertemp": 50,
                    "surfheight": 3,
                    "recommendation": "Surfing conditions are okay, not great."
                },
                "3pm": {
                    "tide": -1,
                    "wind": 10,
                    "watertemp": 65,
                    "surfheight": 1,
                    "recommendation": "Not a good day for surfing."
                }
                ...
            }
        }
    ]
}

В таблице ниже описание для каждого пункта

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

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

🔙

Go next ➡