Стандарты описания API для системных аналитиков26.12.2024 11:15

c2366b436d858dc4d43aef56729b6db1.png

Привет Хабр! Меня зовут Татьяна Ошуркова, я разработчик, аналитик и автор телеграм-канала 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 для получения баланса банковского счета:

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

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

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

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

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

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

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

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

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

IT Talks | Ошуркова Татьяна

t.me

© Habrahabr.ru