REST API — обзор инструментов реализации и документирования для разработчиков

REST API — обзор инструментов реализации и документирования для разработчиков

Сегодня взаимодействие между сервисами различной направленности и уровня разработки через API — обыденное дело. Любой уважающий себя разработчик программного обеспечения хочет получать данные из других систем. Например, вендоры ПО для госзаказчиков просто обязаны обеспечить аутентификацию через ЕСИА (единую систему идентификации и аутентификации) и достичь этого можно только благодаря столь замечательному инструменту.

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

OpenAPI

OpenAPI — спецификация для описания REST API. Также можно рассматривать OpenAPI как спецификацию DITA (Darwin Information Typing Architecture). DITA, в свою очередь, является инструментом для сборки документов из разрозненных фрагментов. Спецификация имеет элементы XML, используемые специально для определения компонентов справки.

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

Элементы OpenAPI — pathsparametersresponses и security, являющиеся объектами JSON, содержат свойства и массивы.

Swagger

Для начала, стоит объяснить, о чем именно сейчас пойдет речь. Мы допускаем, что статью могут открыть те, кто только знакомится с данной областью и некоторые термины могут быть непонятны.

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

Вернемся к теме.

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

Его спецификация — документ с наименованием swagger.json, который создается при помощи цепочки инструментов на основе вашей службы. Файл описывает способы доступа к API через HTTP, управляет пользовательским интерфейсом выглядит примерно следующим образом:

{
    "swagger": "2.0",
    "info": {
        "version": "v1",
        "title": "API V1"
    },
    "basePath": "/",
    "paths": {
        "/api/Todo": {
            "get": {
                "tags": [
                    "Todo"
                ],
                "operationId": "ApiTodoGet",
                "consumes": [],
                "produces": [
                    "text/plain",
                    "application/json",
                    "text/json"
                ],
                "responses": {
                    "200": {
                        "description": "Success",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/TodoItem"
                            }
                        }
                    }
                 }
            },
            "post": {
                …
            }
        },
        "/api/Todo/{id}": {
            "get": {
                …
            },
            "put": {
                …
            },
            "delete": {
                …
    },
    "definitions": {
        "TodoItem": {
            "type": "object",
             "properties": {
                 "id": {
                     "format": "int64",
                     "type": "integer"
                 },
                 "name": {
                     "type": "string"
                 },
                 "isComplete": {
                     "default": false,
                     "type": "boolean"
                 }
             }
        }
    },
    "securityDefinitions": {}
 }

Swagger имеет свой пользовательский веб-интерфейс, содержащий сведения о созданной с помощью спецификации службе.

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

ReDoc

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

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

Как мы уже сказали, ReDoc состоит из трех панелей: справочное меню, документацию по конечным методам, и различные образцы (запросов, ответов, кода).

Основная функция ReDoc — возможность документировать сложные запросы/ответы:

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

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

Для того, чтобы использовать ReDoc, вам не потребуется BackEnd разработчик — все ресурсы (HTML, CSS, JS) объединены в один файл и доступны с CDN разработчика.

Вы можете легко добавлять пользовательские разделы в API-документы благодаря возможности вытягивать заголовки первого уровня из описания Swagger и даже использовать логотип вендора для документов.

Blueprint

Blueprint — мощный высокоуровневый язык описания API для веб-интерфейсов.

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

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

API Blueprint полностью открыт по лицензии MIT. Он не нуждается в закрытой рабочей группе. Вместо этого используется RFC-процесс, аналогичный Rust-языку или Django Enhancement Proposal RFC-процессы.

Тип носителя для API Blueprint — text / vnd.apiblueprint, а стандартное расширение файла — .apib. Если вы используете это расширение, ваши чертежи на GitHub будут выделены синтаксисом.

Пример того, как выглядит синтаксис описания данных:

# Data Structures

## Blog Post (object)
+ id: 42 (number, required)
+ text: Hello World (string)
+ author (Author) - Author of the blog post.

## Author (object)
+ name: Boba Fett
+ email: fett@intergalactic.com
# Blog Posts [/posts]

## Retrieve All Posts [GET]
+ Response 200 (application/json)
    + Attributes (array[Blog Post])

Apiary

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

Примерная схема выглядит так:

Формат: 1A 

# Message of the Day API 
a simple [MOTD] ( https://en.wikipedia.org/wiki/motd ) API. 

# Message [/messages / {id}] 
этот ресурс представляет собой одно конкретное сообщение, идентифицируемое его *id* .

# # Извлечение сообщения [GET] 
извлечение сообщения по его *id* .

+ Ответ 200 (текст/простой) 

Привет Мир!

# # Удалить сообщение [удалить] 
удалить сообщение.
* * Предупреждение: * * это действие * * навсегда * * удаляет сообщение из базы данных.

+ Ответ 204

Несмотря на все преимущества онлайн-редактора, разработчики сервиса оставили возможность использовать командную строку. С помощью нее можно проверять API Blueprint, просматривать документацию, публиковать ее на Apiary .

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

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

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

Snowboard

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

Он может быть интегрирован в процесс CI или использоваться непосредственно с их образом Docker.

Одна из замечательных возможностей Snowboard — это возможность определения шаблона, используемого для рендеринга HTML. Если вы используете Bootstrap (библиотеку компонентов внешнего интерфейса), вы можете сгенерировать ее, используя гармошку и группу списков для меню.

Slate

Slate — полностью настраиваемый фреймворк для создания текстовых редакторов. Он позволяет создавать интуитивно понятные, функциональные текстовые редакторы, такие как: Medium, Dropbox Paper или Google Docs, при этом не усложняя код.

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

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

Slate — это Markdown и когда вы пишете на Slate, вы автоматически пишете и на этом языке разметки. Даже примеры кода написаны на нем.

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

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

Типы API

Web APIs

Web API — это API-интерфейсы, к которым можно получить доступ по протоколу HTTP. API определяет конечные точки, а также допустимые форматы запросов и ответов.

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

Различные Web API предоставляют различные уровни безопасности и конфиденциальности: открытые, внутренние, партнерские.

Open APIs

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

Такие API предназначены для внешних пользователей (например, для разработчиков из другой компании).

Internal APIs

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

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

Partner APIs

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

Composite APIs

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

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

API архитектуры и протоколы

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

REST

REST (representational state transfer) — очень популярная архитектура Web API. Для того, чтобы API подходил под данную архитектуру, необходимо придерживаться следующих правил:

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

JSON-RPC и XML-RPC

RPC — это протокол удаленного процедурного вызова (remote procedural call protocol). XML-RPC использует XML для кодирования вызовов, в то время как JSON-RPC использует JSON. Оба протокола простые и могут содержать несколько параметров, ожидая в ответ всего один результат.

У них есть несколько ключевых функций, отличных от REST:

  • они предназначены для вызова методов, тогда как протоколы REST предлагают передачу документов. Иными словами, REST работает с ресурсами, а RPC — с действиями;
  • URI идентифицируется сервером, но не содержит информации в его параметрах, в то время как REST URI содержит параметры запроса.

SOAP

SOAP (simple object access protocol) — это установленный протокол Web API. Он должен быть расширяемым, нейтральным (поддерживать работы с протоколами HTTP, SMTP, TCP И другими) и независимым (допускать любой стиль программирования).

Спецификация SOAP включает в себя:

  • модель обработки SOAP-сообщения;
  • модель расширяемости возможностей и модулей SOAP;
  • правила привязки протокола и то, как использовать SOAP с таким базовым протоколом, как HTTP;
  • структурированность сообщений SOAP.

Обратите внимание, что можно создать RESTful API при использовании протоколов SOAP, хотя они считаются конкурирующими стандартами.

Курс по документированию REST API

Курс по документированию API. Вольный перевод курса Documenting APIs: a guide for technical writers, составленного Томом Джонсоном, техническим писателем Amazon. Переведен на русский язык.

Посты в блоге о REST API

Информация была полезна для вас?

Расскажите пожалуйста что мы можем улучшить?

оцените контент и участвуйте в выборе трендов

Обзор Apiary

Разработка Мощный стек разработки API. Создан для разработчиков

Подробнее...


Обзор Redoc REST API

Разработка Генератор документации по REST API через нотацию OpenAPI / Swagger

Подробнее...


Обзор Slate API Docs Generator

Хранение & Файлы Slate - красивая статическая документация для вашего API

Подробнее...


Обзор Swagger

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

Подробнее...