Привет Хабр! Меня зовут Татьяна Ошуркова, я разработчик, аналитик и автор телеграм-канала IT Talks. Для системных аналитиков, решающих задачи по работе с требованиями к интеграциям систем, важно понимать, как правильно описывать и документировать API. Стандарты описания API играют ключевую роль в упрощении этого процесса, обеспечивая единый подход, который помогает избежать ошибок и недопонимания между всеми участниками разработки.

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

OpenAPI Specification

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

• Описание требований. Использование OpenAPI помогает четко зафиксировать требования к API, чтобы избежать недопонимания между разработчиками и заказчиком.

• Автоматизация тестирования. На основе спецификации можно создавать тестовые сценарии и проверять корректность работы API.

• Контроль изменений. Аналитик может отслеживать изменения в API и их влияние на существующие интеграции.

Рассмотрим пример описания API с использованием стандарта OpenAPI для интернет-магазина, предоставляющего информацию о товарах:

openapi: 3.0.0
info:
  title: Online Store API
  version: 1.0.0
paths:
  /products:
    get:
      summary: Get list of products
      responses:
        '200':
          description: A list of products

Этот пример описывает API с использованием OpenAPI версии 3.0.0. В секции info указаны метаданные: название API ("Online Store API") и версия (1.0.0), что помогает идентифицировать сервис. В разделе paths описан доступный путь /products, представляющий ресурс для работы с продуктами. Для него определён HTTP-метод GET, который используется для получения списка продуктов. Указан успешный ответ с кодом 200 и пояснением, что возвращается список продуктов. Такая спецификация делает API понятным и облегчает его интеграцию.

AsyncAPI Specification

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

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

• Управление событиями. Дает возможность проектировать события и форматы сообщений между компонентами системы.

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

Рассмотрим пример описания API с использованием AsyncAPI для системы мониторинга температуры:

asyncapi: 2.0.0
info:
  title: Temperature Monitoring API
  version: 1.0.0
channels:
  sensors/temperature:
    publish:
      summary: Publishes temperature data
      message:
        contentType: application/json
        payload:
          type: object
          properties:
            temperature:
              type: number

Этот пример представляет собой спецификацию API, описанную с использованием стандарта AsyncAPI версии 2.0.0. Этот стандарт применяется для описания событийно-ориентированных систем и взаимодействий через асинхронные протоколы, такие как MQTT, AMQP или WebSockets.

В секции info указаны метаданные API: название ("Temperature Monitoring API") и версия (1.0.0), что помогает идентифицировать сервис. В разделе channels описан канал sensors/temperature, который используется для публикации данных о температуре. Операция publish указывает, что API отправляет сообщения через этот канал.

Сообщение описано через структуру message, в которой указано, что данные отправляются в формате application/json. Поле payload описывает формат содержимого: это объект с единственным свойством temperature, которое представляет числовое значение температуры.

GraphQL Schema Definition Language

GraphQL — это язык запросов, который позволяет клиентам формировать запросы, получая только необходимые данные. В отличие от REST, где существует множество конечных точек, в GraphQL используется одна точка входа, что упрощает работу с данными и снижает объем передаваемой информации. Для аналитика использование GraphQL в работе с требованиями может решать следующий ряд задач:

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

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

• Поддержка сложных запросов. Упрощает получение связанных данных (например, товаров и их категорий).

Рассмотрим пример с использованием GraphQL для получения списка товаров и категорий:

type Product {
  id: ID!
  name: String!
  price: Float!
  category: Category
}

type Category {
  id: ID!
  name: String!
}

type Query {
  products: [Product]
  categories: [Category]
}

Этот пример описывает GraphQL-схему, определяющую структуру данных и доступные операции. Тип Product включает обязательные поля id, name, price и опциональное поле category, которое связано с типом Category. Тип Category содержит обязательные поля id и name. В секции Query описаны операции для получения данных: products возвращает список продуктов, а categories — список категорий. Такая структура позволяет клиенту запрашивать только нужные данные, делая API гибким и эффективным.

RAML (RESTful API Modeling Language)

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

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

Для аналитика использование RAML в работе может решать следующий ряд задач:

• Структурирование документации. RAML помогает создать четкую и логичную структуру для API, что упрощает поддержку и тестирование.

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

• Ускорение проектирования. Возможность переиспользования компонентов ускоряет разработку новых API.

Рассмотрим пример с использованием RAML для управления заказами в системе доставки:

#%RAML 1.0
title: Delivery Service API
version: 1.0
/orders:
  get:
    description: Get list of orders
    responses:
      200:
        body:
          application/json:
            type: Order[]

Этот пример представляет спецификацию API, описанную с использованием RAML 1.0. Заголовок title указывает название API ("Delivery Service API"), а version обозначает текущую версию (1.0). В разделе /orders описан путь для получения списка заказов с помощью HTTP-метода GET. Указано, что успешный ответ с кодом 200 возвращает данные в формате application/json, представляющие массив объектов типа Order. Эта структура позволяет четко описать, как клиенты могут взаимодействовать с API.

WSDL (Web Services Description Language)

WSDL — это XML-документ, который используется для описания SOAP API. Он описывает контракты взаимодействия, включая доступные методы, параметры, типы данных и коды ошибок. WSDL необходим для работы с веб-сервисами в старых корпоративных системах, где требуется строгое соблюдение контракта. Для аналитика, работающего с протоколом SOAP, использование WSDL в работе может решать следующий ряд задач:

• Формализация взаимодействий. SOAP API с WSDL идеально подходит для систем с жесткими требованиями к интерфейсу и контрактам.

• Контроль точности. Описание с WSDL помогает избежать ошибок в интеграции благодаря четко зафиксированным правилам.

• Совместимость. Используется для интеграции с устаревшими системами, где важно сохранить совместимость.

Рассмотрим пример с использованием WSDL для получения баланса банковского счета:

<definitions>
  <message name="GetAccountBalanceRequest">
    <part name="accountId" type="xsd:string"/>
  </message>
  <message name="GetAccountBalanceResponse">
    <part name="balance" type="xsd:decimal"/>
  </message>
  <portType name="AccountService">
    <operation name="GetAccountBalance">
      <input message="tns:GetAccountBalanceRequest"/>
      <output message="tns:GetAccountBalanceResponse"/>
    </operation>
  </portType>
</definitions>

В разделе message определены два сообщения: запрос GetAccountBalanceRequest, содержащий параметр accountId (строка), и ответ GetAccountBalanceResponse, включающий параметр balance (десятичное число).

Секция portType описывает интерфейс сервиса AccountService, который включает операцию GetAccountBalance. Эта операция принимает входное сообщение GetAccountBalanceRequest и возвращает выходное сообщение GetAccountBalanceResponse. Такая структура определяет взаимодействие клиента и сервера через SOAP, включая параметры запроса и ожидаемые ответы.

Подведем итоги

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

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

• Проектирование архитектуры API: Как правильно проектировать, развивать и эксплуатировать API. Брайант Д., Гоф Д., Оберн М.

• Паттерны проектирования API. Джей Джей Гивакс

• Непрерывное развитие API. Правильные решения в изменчивом технологическом ландшафте. Амундсен Майк, Митра Ронни

• Проектирование веб-API. Лоре Арно