API

Cредства разработки

Сергей Маковеев / @sergeymakoveev

Тенденции

• применение SPA в качестве архитектуры веб-приложений подразумевает выделение API в качестве обязательной структурной единицы приложения, наряду с frontend и backend

• более высокая значимость API в SPA-приложениях по-сравнению с приложениями классической архитектуры

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

Практика

• в начале процесса разработки приложения frontend и backend реализуют “наброски” API каждый собственными средствами

• функциональные и интеграционные тесты frontend, backend и api зачастую требуют наличия “эталоной” реализации API

• выделение API как равноправной части приложения подразумевает применение специализированных средств разработки (стандарты, языки, инструменты)

Необходима единая “площадка” для проектирования, документирования, моделирования и коммуникации со спецификацией API

Площадки для разработки API

• документированный код встроенными средствами языка
  Javadoc (Java), JSDoc (Node JS/JavaScript), Docstring (Python)
  – механизм изначально предназначен не для проектирования
  – привязка к коду и языку

• специализированные фреймворки
  JSON Server (NodeJS), Eve (Python)
  ✚ изначально предназначены для эмуляции
  ✚ позволяют реализовать эмуляцию API почти без кодирования
  ✚ используют синтаксис JSON
  – привязка к фреймворку

• стандартизированные/специфицированные описания
  API Blueprint, Open API (Swagger), RAML
  ✚ изначально предназначены для полного стека разработки API
  ✚ используют доступный и общепринятый синтаксис (XML/JSON/YAML/Markdown)
  ✚ позволяют сосредоточится на проектировании
  ✚ поддержка в виде библиотек для различных языков и фреймворков
  ✚ множество инструментов и сервисов (клиенты, редакторы, эмуляторы, валидаторы)

API Blueprint a powerful high-level API description language for web APIs

• разработчик: Apiary
• спецификация: API Blueprint Specification
• синтаксис: базируется на Markdown
• синтаксис описания данных: JSON, JSON Schema, MSON
• примеры: API Blueprint Examples, Polls API, Example API Blueprint

• преимущества:
  – наглядность, самодокументируемость
  – определен media type “text/vnd.apiblueprint”, расширение файлов “.apib”
  – поддерживается GitHub
  – отличный онлайн-сервис app.apiary.io

• недостатки:
  – синтаксис: поддерживается только Markdown, сложность восприятия структуры
  – авторизация/аутентификация: не реализовано
  – модульность: не реализовано
  – разработка: недостаточно активная

API Blueprint a powerful high-level API description language for web APIs

Инструменты:

• полный список
• онлайн-сервис app.apiary.io
  – редактор с подсветкой и валидацией синтаксиса
  – документированное представление с интерактивным клиентом
  – эмулятор
  – инспектор запросов к эмулятору
  – поддержка Swagger
  – консольный клиент
  – интеграция с GitHub, Bitbucket
• api-mock
  – эмулятор
  – zero-coding

Open API (Swagger) a simple yet powerful representation of your RESTful API

• разработчики: SmartBear, Apiary, Atlassian, Google, IBM, Microcoft, PayPal
• спецификация: OpenAPI Specification 2.0, Swagger 2.0
  1 января 2016 года спецификация Swagger передана в Open API
• синтаксис: JSON, YAML
• синтаксис описания данных: JSON, JSON Schema
• примеры: OpenAPI examples, examples in Swagger Editor, Instagram API

• преимущества:
  – синтаксис: поддерживаются стандартные JSON и YAML
  – модульность, наследование, полиморфизм: реализовано
  – авторизация/аутентификация: реализовано
  – разработка: активная
  – редактор: прекрасная реализация
  – поддерживается Postman, app.apiary.io

• недостатки:
  – отсутствует реализация эмулятора, для работы которого достаточно указать файл описания API

Open API (Swagger) a simple yet powerful representation of your RESTful API

Инструменты (core tools, community tools):

• Swagger Editor , пример
  – редактор с подсветкой и валидацией синтаксиса
  – документированное представление с интерактивным клиентом

• Swagger UI , пример
  – документированное представление с интерактивным клиентом

• Swagger Validator, пример
  – http://online.swagger.io/validator/debug?url=
  – онлайн-валидатор

• эмуляторы для NodeJS:
  – Swagger Express Middleware
  – Swagger Server

RAML
RESTful API Modeling Language

• разработчики: MuleSoft, PayPal, Cisco
• спецификация: RAML Version 0.8, RAML Version 1.0
• синтаксис: базируется на YAML 1.2
• синтаксис описания данных: JSON, JSON Schema, XML Schema
• примеры: RAML APIs, Developer portal, Notes Example API, Instagram API

• преимущества:
  – модульность: реализовано
  – наследование: реализовано
  – авторизация/аутентификация: реализовано
  – поддерживается Postman
  – реализованы конвертеры RAML <> OpenAPI (Swagger)
  – поддерживается GitHub

• недостатки:
  – поддерживается только нестандартный Raml

RAML
RESTful API Modeling Language

Инструменты:

• Anypoint Platform (онлайн-IDE)
• API Workbench (IDE, базируется на ATOM)

• API Designer
  – редактор с подсветкой и валидацией синтаксиса
  – документированное представление с интерактивным клиентом
  – пример, Instagram API zip

• API Console
  – документированное представление с интерактивным клиентом
  – пример

• osprey – прокси-сервер с валидацией
• osprey-cli – консольный клиент
• osprey-mock-service – эмулятор

Заключение

Cуществуют развитые стандарты и спецификации, предназначенные для описания и документирования API с использованием доступного и общепринятого синтаксиса (XML/JSON/YAML/Markdown).

Для многих из них разработаны средства, позволяющие на основе этого описания:

• генерировать документацию
• моделировать API в виде независимого сервиса
• генерировать код контроллеров для наиболее популярных фреймворков
• настраивать роутинги и валидацию данных запросов внутри приложения
• валидировать данные, которыми обмениваются backend и frontend