Язык моделирования RESTful API ( RAML ) — это язык на основе YAML для описания статических API (но не REST API). [2] Он предоставляет всю информацию, необходимую для описания API на уровне 2 модели зрелости Ричардсона . Несмотря на то, что RAML разработан с учетом API RESTful, он не способен описывать API, которые подчиняются всем ограничениям REST ( в частности, он не может описывать API, подчиняющийся HATEOAS ). Оно поощряет повторное использование, позволяет делать открытия и обмениваться образцами и направлено на появление лучших практик на основе заслуг. [3]
RAML был впервые предложен в 2013 году. Первоначальная спецификация RAML была написана Ури Саридом, Эмилиано Лесенде, Сантьяго Вакасом и Дамианом Мартинесом и получила поддержку таких технологических лидеров, как MuleSoft, AngularJS, Intuit, Box, PayPal, Programmable Web и API Web Science. Кин Лейн, SOA Software и Cisco. [4] Разработкой управляет рабочая группа RAML. [5] В состав нынешней рабочей группы входят технологические лидеры MuleSoft (Ури Сарид, технический директор), AngularJS (Миско Хевери, основатель проекта), Intuit (Иван Лазаров, главный архитектор предприятия), Airware (Питер Рексер, директор по продукту — платформа разработки). , Programmable Web и API Science (Джон Массер, основатель), SOA Software (Тони Галлотта, директор по развитию), Cisco (Джайдип Субедар, старший менеджер, управление продуктами — группа решений по интеграции приложений), VMware (Кевин Даффи, старший инженер MTS) , Akamai Technologies (Роб Дейно, директор по архитектуре платформы OPEN API Akamai) и Restlet (Жером Лувель, технический директор и основатель). RAML является торговой маркой MuleSoft. [6]
Очень немногие существующие API соответствуют точным критериям, которые можно отнести к RESTful API. Следовательно, как и большинство инициатив API в 2010-х годах, RAML изначально сосредоточился на основах API, включая ресурсы, методы, параметры и тела ответов, которые не обязательно должны быть гипермедиа. Есть планы перейти к более строгим API-интерфейсам RESTful, если позволит развитие технологий и рынка. [ нужна цитата ]
Существует ряд причин, по которым RAML перестал быть проприетарным языком поставщиков и оказался интересным для более широкого сообщества API: [7]
Новая организация, спонсируемая Linux Foundation , под названием Open API Initiative, была создана в 2015 году для стандартизации описания HTTP API. Членами-учредителями стали ряд компаний, включая SmartBear , Google , IBM и Microsoft . [11] [12] SmartBear передал новой группе спецификацию Swagger. RAML и API Blueprint также находятся на рассмотрении группы. [13] [14]
Это пример RAML-файла. Как и в YAML, отступы показывают вложенность.
#%RAML 0,8 Название : API мировой музыки baseUri : http://example.api.com/{version} версия : v1 черты : - на странице : Параметры запроса : страницы : описание : количество возвращаемых страниц. тип : номер - защищено : !include http://raml-example.com/secured.yml /песни : это : [ размещено на странице , защищено ] получать : Параметры запроса : жанр : описание : фильтровать песни по жанру почта : /{идентификатор песни} : получать : ответы : 200 : тело : приложение/json : схема : | { "$schema": "http://json-schema.org/schema", "тип": "объект", "description": "Каноническая песня", "характеристики": { "title": { "type": "string" }, "художник": { "тип": "строка" } }, "обязательно": [ "название", "исполнитель"] } приложение/xml : удалить : описание : | Этот метод *удалит* **отдельную песню**.Некоторые моменты:
Кроме того, вы можете преобразовать свою спецификацию RAML в OpenAPI или API Blueprint с помощью APIMATIC, что позволит вам использовать дополнительные шлюзы API.