Спецификации api: Расшифровка классификации масла по API

alexxlab

Импорт спецификации OpenAPI в службу управления API Azure

Twitter LinkedIn Facebook Адрес электронной почты

  • Статья
  • Чтение занимает 4 мин

В этой статье показано, как импортировать API серверной части «Спецификация OpenAPI», расположенный по адресу https://conferenceapi. azurewebsites.net?format=json. Этот API серверной части предоставляется корпорацией Майкрософт. Он размещен в Azure. Также здесь показано, как проверить API службы управления API.

Вы узнаете, как выполнять следующие задачи:

  • Импорт спецификации OpenAPI с помощью портала Azure, Azure CLI или Azure PowerShell
  • проверка API на портале Azure;

Примечание

Ограничения импорта API описаны в статье Ограничения импорта API и известные проблемы.

Предварительные требования

  • Экземпляр управления API. Если у вас ее еще нет, выполните инструкции из следующего краткого руководства: Создание экземпляра службы управления API Azure.

  • Azure CLI

    • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в кратком руководстве по Azure Cloud Shell — Bash.

    • Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в разделе Запуск Azure CLI в контейнере Docker.

      • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, приведены в статье Вход с помощью Azure CLI.

      • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

      • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

  • Azure PowerShell

    • Если вы используете Azure PowerShell локально:
      • Установите модуль Az PowerShell.
      • Подключитесь к учетной записи Azure с помощью командлета Connect-AzAccount.
    • Если вы используете Azure Cloud Shell:
      • Дополнительные сведения см. в статье Общие сведения об Azure Cloud Shell.

Импорт API серверной части

  • Портал
  • Azure CLI
  • PowerShell

  1. Перейдите к экземпляру Управления API на портале Azure.

  2. В меню слева выберите API

    >+ Добавить API.

  3. В разделе Создание из определения выберите OpenAPI.

  4. Введите параметры API. Вы можете задать значения во время создания или настроить их позже, перейдя на вкладку Параметры. Эти параметры описаны в руководстве Импорт и публикация первого интерфейса API.

  5. Нажмите кнопку создания.

Проверка нового API на портале

Операции можно вызывать непосредственно на портале, что позволяет администраторам просматривать и тестировать операции API.

  1. Выберите API, созданный на предыдущем шаге.

  2. Откройте вкладку Тест.

  3. Выберите операцию.

    На странице отобразятся поля для параметров запроса и для заголовков.

    Примечание

    В консоли тестирования служба «Управление API» автоматически заполняет заголовок Ocp-Apim-Subscription-Key и настраивает ключ подписки встроенной подписки с доступом. Этот ключ обеспечивает доступ к каждому API в экземпляре управления API. При необходимости можно отобразить заголовок Ocp-Apim-Subscription-Key , щелкнув значок «глаз» рядом с HTTP-запросом.

  4. В зависимости от операции введите значения параметров запроса, значения заголовков или текст запроса. Нажмите кнопку

    Отправить.

    Если тест пройдет успешно, приложение серверной части передаст код ответа 200 — OK и некоторые данные.

Сведения об отладке API см. в статье Руководство. Отладка API с помощью трассировки запросов.

Добавление других интерфейсов API

Вы можете составить API из API, предоставляемых различными службами, включая:

  • Спецификацию OpenAPI
  • A SOAP API
  • Веб-приложение, размещенное в Службе приложений Azure
  • Приложение-функция Azure
  • Azure Logic Apps
  • Azure Service Fabric

Добавьте другой API к уже существующему API, выполнив следующие действия.

Примечание

После импорта другого API операции добавляются к текущему API.

  1. Перейдите к экземпляру управления API Azure на портале Azure.

  2. Выберите API на странице Обзор или в меню слева.

  3. Щелкните …рядом с API, к которому нужно добавить другой API.

  4. В раскрывающемся меню выберите Импорт.

  5. Выберите службу, из которой следует импортировать API.

  • Ограничения импорта API
  • Импорт спецификации OpenAPI
  • Импорт SOAP API
  • Импорт SOAP API и преобразование в REST
  • Импорт API Службы приложений
  • Импорт API контейнерного приложения
  • Импорт WebSocket API
  • Импорт API GraphQL
  • Импорт схемы GraphQL и настройка сопоставителей полей
  • Импорт приложения-функции Azure
  • Импорт приложения логики Azure
  • Импорт службы Service Fabric
  • Импорт метаданных SAP OData
  • Изменение API

Дальнейшие действия

  • Создание и публикация продукта
  • Преобразование и защита опубликованного API

Спецификация взаимодействия по API — Раздел помощи

Актуальная версия используемой спецификации JSON-RPC 2.

0 (http://www.jsonrpc.org/specification)

  • Обращение к API
  • Получение токена взаимодействия с API
  • Формат запроса
  • Формат ответа

Обращение к API

Обращение к API происходит по протоколу HTTP/HTTPS и использует метод POST передачи данных в виде JSON. В самом запросе URI указывает на объект (класс), а тело запроса содержит метод этого класса и параметры вызова.

Метод по умолчанию для всех объектов «index«.

Получение токена для взаимодействия с API

Для большинства запросов к API вам потребуется передавать токен, полученный после авторизации. Получить токен можно отправив следующий запрос на URL https://api.sweb.ru/notAuthorized/


{"jsonrpc":"2.0","method":"getToken","params":{"login":"< >","password":"< >"}}

Где:

  • <ваш логин> — логин в Личный кабинет аккаунта
  • <ваш пароль> — пароль в Личный кабинет аккаунта

В ответе в параметре result придет токен, который нужно будет передавать при взаимодействии с API. Пример запроса и ответа:


curl  -H 'Content-Type: application/json; charset=utf-8' \
      -H 'Accept: application/json' \
      --data '{"jsonrpc":"2.0","method":"getToken","params":{"login":"vkireev166","password":"


Kmm3sWd5fkZws$hd"}}' \
      https://api.sweb.ru/notAuthorized/


{"jsonrpc":"2.0","version":"1.127.20220504121319","id":"20220505104244.40FxsQ16Ff","result":"
hdlhcdkd0bid6c29fhfu1s7rtu.202357ec-d5ca-4a0a-846c-2dabe0266ef4"}

Формат запроса

Пример формата запроса.

Request URL: https://api.sweb.ru/domains/ (обращение к объекту класса Domains)

Заголовки запроса


Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Bearer <,   >

Все запросы должны содержать заголовок с токеном авторизации, кроме запросов к общедоступным методам https://api.

sweb.ru/notAuthorized/

POST данные в запросе:


{"jsonrpc":"2.0","version":"1.62.20210215150032","method":"add","params":{"domain":"vpstest.ru"},"id":"
20183994338.43VSEkfGFh","user":"vhphpunit"}

Описание параметров:

  • jsonrpc — текущая версия JSON-RPC
  • version — текущая версия клиента приложения. Носит только информационный характер, используется в отчетах об ошибках method — публичный метод объекта Domains
  • params — ассоциативный массив параметров метода (ключ элемента массива — имя параметра)
  • id — уникальный идентификатор запроса
  • user — идентификатор пользователя, который отправляет запрос. Носит только информационный характер, сверяется со значением сессии токена и в случае расхождения приводит к ошибке авторизации

Параметр jsonrpc является обязательным. Если не передан id, то он будет сформирован на стороне API. Если не передан method будет вызван дефолтный метод для объекта.

Формат ответа

Успешный ответ

В случае, если на стороне API не возникло ошибок возвращается результат работы вызванного метода в виде JSON. Пример ответа:


{"jsonrpc":"2.0","version":"1.62.20210215150032","id":"20183995523.MO4E9baKRr","result":{"balance":
{"real_balance":500,"bonus_balance":0}}}

Описание параметров:

  • jsonrpc — текущая версия JSON-RPC
  • version — текущая версия клиента
  • result — результат, который возвращает вызванный метод
  • id — уникальный идентификатор ответа, если был в запросе, то совпадает с ним

Все параметры в ответе являются обязательными.

Сообщение об ошибке

В случае возникновения ошибок, ответ вместо параметра result будет содержать error с двумя значениями code и message. Например:


{"jsonrpc":"2.0","version":"0.1","id":"20183910121.UPNWsDxwmn","error":{"code":-32601,"message":"Object not
found"}}

Описание параметров:

  • jsonrpc — текущая версия JSON-RPC
  • version — текущая версия клиента
  • error — объект ошибки, который содержит (code — код ошибки http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php и message — текст ошибки)
  • id — уникальный идентификатор ответа, если был в запросе, то совпадает с ним

Все параметры в ответе являются обязательными. Важно: HTTP-код ответа при этом всегда будет 200 Расширенное сообщение о результатах работы метода

Если метод кроме успешного или неуспешного результата должен передать клиенту какое-то кастомизированное сообщение или данные, то применяется общий тип ExtendedResult для таких ответов. Например:


{"jsonrpc":"2.0","version":"1.62.20210215150032","id":"20183995523.MO4E9baKRr","result":{"extendedResult":
{"code":1,"message":"\u0417\u0430\u044f\u0432\u043a\u0430 #180047823 \u043f\u0440\u0438\u043d\u044f\u0442\u0430
\u0432 \u0440\u0430\u0431\u043e\u0442\u0443","data":[]}}}


{"jsonrpc":"2.0","version":"1.62.20210215150032","id":"20183995523.MO4E9baKRr","result":{"extendedResult":
{"code":0,"message":"\u0417\u043e\u043d\u0430 .child \u043d\u0435
\u043f\u043e\u0434\u0434\u0435\u0440\u0436\u0438\u0432\u0430\u0435\u0442\u0441\u044f \u0434\u043b\u044f
\u0440\u0435\u0433\u0438\u0441\u0442\u0440\u0430\u0446\u0438\u0438","data":[]}}}

Описание параметров extendedResult:

  • code — 1 — успешное выполнение, 0 — ошибка
  • message — кастомизированное сообщение о результате
  • data — объект дополнительных данных (может быть пустым)

Руководство по документации API и рекомендации

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

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

В этом руководстве по документации API мы рассмотрим основы документирования API и различных типов документации. Мы также подробно рассмотрим основы часто задаваемых вопросов «что такое документация по API?» с примерами.

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

Документы по API или документы с описанием API — это набор ссылок, руководств и примеров, которые помогают разработчикам использовать свой API.

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

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

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

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

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

Ваша документация должна полностью описывать функциональность API, быть точной, обучающей и вдохновлять на использование. Это большая работа, которую можно условно разделить на три типа:

  • Справочник и функциональность
  • Руководства и учебные пособия
  • Примеры и варианты использования

Мы обсудим их подробно, но вы можете думать о них как о переходе от континуума фактов к контексту. Ссылка описывает конечные точки API, он выкладывает все части. Гиды берут некоторые из этих кусочков и начинают их складывать. вместе, объясняя, почему вы будете использовать эти части. Наконец, примеры предлагают очень конкретное решение, решая общую проблему. проблема.

Как вы увидите, лучшая документация по API содержит все три типа контента.

Теперь, когда мы знаем, какие типы документации искать, давайте рассмотрим несколько примеров отличной документации REST API. В течение многих лет при обсуждении документации по API продолжают всплывать два имени: Stripe и Twilio.

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

Справочник по API Stripe почти стал стандартом своей полноты и возможность просмотра.

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

Руководства Twilio примечательны как охватом языков программирования, так и как они проводят вас шаг за шагом.

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

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

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

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

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

Stripe, Twilio и Heroku — все компании, которые продают напрямую разработчикам. У них есть целые команды, чтобы строить и поддерживать свою документацию и другие ресурсы для разработчиков. Когда вы сами пишете документацию по API, будьте готовы большая часть времени по крайней мере одного инженера или технического писателя для первоначальной сборки. Также помните, что, как и любой программное обеспечение, документация потребует обслуживания. Вам часто потребуется дополнительное время от инженеров, чтобы исправить или обновите свои документы.

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

Наконец, вы можете использовать размещенную опцию, такую ​​как Stoplight, которая предоставляет красивую настраиваемую документацию. Спускаться этот маршрут обычно требует наименьшего количества инженерного времени; чтобы ваша команда сосредоточилась на своем основном бизнесе. С многие из этих услуг предоставляются в облаке, обновления выполняются автоматически, а техническое обслуживание минимально.

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

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

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

Начните с вашего документа спецификации API

Лучшее место для начала создания справочника по API — машиночитаемое описание вашего API. Есть здесь есть несколько вариантов, включая OpenAPI, Swagger и RAML. Тем не менее, индустрия сплотилась вокруг OpenAPI. Инициатива, созданная консорциумом и управляемая Linux Foundation.

Спецификация OpenAPI существует в двух вариантах: версия 2, основанная на исходной спецификации Swagger, и более новая версии 3. Последняя версия — это путь вперед, но вы все равно найдете инструменты, созданные на основе версии 2, и вам, возможно, потребуется конвертировать между ними.

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

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

Показать и рассказать о функциях API

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

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

Если вы начали с определения OpenAPI, объекты ответов (и другие связанные компоненты в версии 3) где вы будете включать эти важные данные. Когда разработчик может видеть, чего ожидать, он может лучше предсказать, как они могут интегрироваться с API без совершения звонков в реальном времени.

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

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

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

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

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

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

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

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

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

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

  1. Скачать этот код
  2. Замените ключ API
  3. Запустить код

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

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

Как и в случае с руководствами, понимание проблем, которые решают ваши разработчики, поможет вам определить, какие примеры следует использовать. Поделиться. Вы также можете черпать вдохновение у существующих разработчиков и делиться уже популярными вариантами использования.

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

Сделайте это чьей-то работой. Это не обязательно должна быть их работа, но может быть. Главное, что у тебя есть кто-то следит за тем, как разработчики воспринимают вашу документацию.

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

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

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

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

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

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

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

JSON:API — Спецификация для создания API в JSON

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

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

Вот пример ответа из блога, реализующего JSON:API:

.
 {
  "ссылки": {
    "я": "http://example. com/articles",
    "далее": "http://example.com/articles?page[offset]=2",
    "последний": "http://example.com/articles?page[offset]=10"
  },
  "данные": [{
    "тип": "статьи",
    "идентификатор": "1",
    "атрибуты": {
      "title": "JSON:API рисует мой велосипедный сарай!"
    },
    "отношения": {
      "автор": {
        "ссылки": {
          "я": "http://example.com/articles/1/relationships/author",
          "связанный": "http://example.com/articles/1/author"
        },
        "данные": { "тип": "люди", "id": "9" }
      },
      "Комментарии": {
        "ссылки": {
          "я": "http://example.com/articles/1/relationships/comments",
          "связанный": "http://example.com/articles/1/comments"
        },
        "данные": [
          { "тип": "комментарии", "идентификатор": "5" },
          { "тип": "комментарии", "идентификатор": "12" }
        ]
      }
    },
    "ссылки": {
      "я": "http://example.com/articles/1"
    }
  }],
  "включено": [{
    "тип": "люди",
    "идентификатор": "9",
    "атрибуты": {
      "firstName": "Дэн",
      "lastName": "Гебхардт",
      "твиттер": "дгеб"
    },
    "ссылки": {
      "я": "http://example. com/people/9"
    }
  }, {
    "тип": "комментарии",
    "идентификатор": "5",
    "атрибуты": {
      "тело": "Первый!"
    },
    "отношения": {
      "автор": {
        "данные": { "тип": "люди", "id": "2" }
      }
    },
    "ссылки": {
      "я": "http://example.com/comments/5"
    }
  }, {
    "тип": "комментарии",
    "идентификатор": "12",
    "атрибуты": {
      "body": "Мне больше нравится XML"
    },
    "отношения": {
      "автор": {
        "данные": { "тип": "люди", "id": "9" }
      }
    },
    "ссылки": {
      "я": "http://example.com/comments/12"
    }
  }]
}

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

JSON:API также охватывает создание и обновление ресурсов, а не только ответов.

Оставить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *