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

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

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

OpenAPI

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

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

Элементы OpenAPI — paths, parameters, responses и 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, хотя они считаются конкурирующими стандартами.