РАМЛ (программное обеспечение)

РАМЛ
Расширение имени файла	.raml
Тип интернет-СМИ	приложение/raml+yaml
Разработано	Рабочая группа RAML
Последний выпуск	1.0 ; 16 мая 2016 г.
Расширено с	ЯМЛ
Стандартный	github .с /raml-org /raml-спецификация /блоб /владелец /версии /рамл-10 /рамл-10 .md /
Веб-сайт	Рамл .org

Язык моделирования RESTful API ( RAML ) — это язык на основе YAML для описания статических API (но не REST API). ^{[ 2 ]} Он предоставляет всю информацию, необходимую для описания API на уровне 2 модели зрелости Ричардсона . Несмотря на то, что RAML разработан с учетом RESTful API, он не способен описывать API, которые подчиняются всем ограничениям REST ( подчиняющийся HATEOAS в частности, он не может описывать API, ). Оно поощряет повторное использование, позволяет делать открытия и обмениваться образцами и направлено на появление лучших практик на основе заслуг. ^{[ 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 ]}

RAML имеет открытый исходный код вместе с инструментами и анализаторами для распространенных языков. Разработку RAML будет контролировать руководящий комитет, состоящий из практиков API и UX, а вокруг RAML развивается новая экосистема сторонних инструментов. ^{[ 8 ]}
Первоначально MuleSoft начала использовать Swagger (теперь спецификация OpenAPI ), но решила, что он лучше всего подходит для документирования существующего API, а не для разработки API с нуля. RAML возник из-за необходимости поддержки предварительного проектирования API на кратком, ориентированном на человека языке. ^{[ 9 ]}
Описания API часто бывают многословными и повторяющимися, что может затруднить их понимание и использование, а также замедлить внедрение API. RAML представил языковые функции, которые поддерживают структурированные файлы и наследование, решающие межсекторальные проблемы. ^{[ 10 ]}

Новая организация, спонсируемая 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

  title: World Music API
  baseUri: http://example.api.com/{version}
  version: v1
  traits:
    - paged:
        queryParameters:
          pages:
            description: The number of pages to return
            type: number
    - secured: !include http://raml-example.com/secured.yml
  /songs:
    is: [ paged, secured ]
    get:
      queryParameters:
        genre:
          description: filter the songs by genre
    post:
    /{songId}:
      get:
        responses:
          200:
            body:
              application/json:
                schema: |
                  { "$schema": "http://json-schema.org/schema",
                    "type": "object",
                    "description": "A canonical song",
                    "properties": {
                      "title":  { "type": "string" },
                      "artist": { "type": "string" }
                    },
                    "required": [ "title", "artist" ]
                  }
              application/xml:
      delete:
        description: |
          This method will *delete* an **individual song**

Некоторые моменты:

строка 7, 12: определяет черты, вызываемые в нескольких местах
строка 12: включаемый файл
строки 13, 14: определить тип данных «ресурса» «/songs»; использует ранее определенные черты
строки 15, 19, 37: определяют HTTP методы
строка 25, 36: типы MIME .

Шлюзы API, поддерживающие RAML

Позвони ему
МулСофт
AWS API Gateway от AWS (через AWS API Gateway Importer )
Аканах
Рестлет

Кроме того, вы можете преобразовать свою спецификацию RAML в OpenAPI или API Blueprint с помощью APIMATIC , что позволит вам использовать дополнительные шлюзы API.

См. также

Альтернативные языки моделирования HTTP API

Примечания

^ Не зарегистрирован в IANA.

Ссылки

^ «Анонсируем RAML 1.0 GA | Блог RAML» . Проверено 11 августа 2016 г.
^ «РАМЛ 100.о» . Гитхаб . Проверено 26 мая 2017 г.
^ «RAML — язык моделирования RESTful API» . Проверено 15 июля 2014 г.
^ «RAML или OpenAPI — как насчет обоих? — Интеграция DZone» . dzone.com . Проверено 4 октября 2017 г.
^ «Рабочая группа РАМЛ» .
^ «RAML — Сведения о торговой марке» . 26 мая 2017 г.
^ «Почему RAML — это больше, чем просто еще одна проприетарная спецификация» . 11 апреля 2014 г.
^ «Инструменты проектирования API от RAML» . 3 марта 2014 г.
^ «Anypoint для API: интервью с Ури Саридом» . 25 февраля 2014 г.
^ «Пример проектирования API с использованием RAML» . 11 апреля 2014 г.
^ «SmartBear и Linux Foundation запускают инициативу Open API для развития Swagger» . Программируемая сеть . 10 ноября 2015 г. Архивировано из оригинала 09.11.2016 . Проверено 21 апреля 2016 г.
^ «Новый совместный проект по расширению спецификации Swagger для создания связанных приложений и сервисов» . www.linuxfoundation.org . Архивировано из оригинала 27 апреля 2016 г. Проверено 22 апреля 2016 г.
^ Моншель, Ив де (14 декабря 2015 г.). «В 2016 году потребность в метаязыке API выкристаллизуется» . Инфомир . Проверено 25 апреля 2016 г.
^ «Amazon API Gateway теперь поддерживает импорт определений Swagger» . ИнфоQ . Проверено 25 апреля 2016 г.

Внешние ссылки

[1] Не зарегистрирован в IANA.

[2] «Анонсируем RAML 1.0 GA | Блог RAML» . Проверено 11 августа 2016 г.

[spec-3] «РАМЛ 100.о» . Гитхаб . Проверено 26 мая 2017 г.

[4] «RAML — язык моделирования RESTful API» . Проверено 15 июля 2014 г.

[5] «RAML или OpenAPI — как насчет обоих? — Интеграция DZone» . dzone.com . Проверено 4 октября 2017 г.

[6] «Рабочая группа РАМЛ» .

[7] «RAML — Сведения о торговой марке» . 26 мая 2017 г.

[8] «Почему RAML — это больше, чем просто еще одна проприетарная спецификация» . 11 апреля 2014 г.

[9] «Инструменты проектирования API от RAML» . 3 марта 2014 г.

[10] «Anypoint для API: интервью с Ури Саридом» . 25 февраля 2014 г.

[11] «Пример проектирования API с использованием RAML» . 11 апреля 2014 г.

[12] «SmartBear и Linux Foundation запускают инициативу Open API для развития Swagger» . Программируемая сеть . 10 ноября 2015 г. Архивировано из оригинала 09.11.2016 . Проверено 21 апреля 2016 г.

[13] «Новый совместный проект по расширению спецификации Swagger для создания связанных приложений и сервисов» . www.linuxfoundation.org . Архивировано из оригинала 27 апреля 2016 г. Проверено 22 апреля 2016 г.

[14] Моншель, Ив де (14 декабря 2015 г.). «В 2016 году потребность в метаязыке API выкристаллизуется» . Инфомир . Проверено 25 апреля 2016 г.

[15] «Amazon API Gateway теперь поддерживает импорт определений Swagger» . ИнфоQ . Проверено 25 апреля 2016 г.

[ н 1 ]

[ 1 ]

[ 2 ]

[ 3 ]

[ 4 ]

[ 5 ]

[ 6 ]

[ 7 ]

[ 8 ]

[ 9 ]

[ 10 ]

[ 11 ]

[ 12 ]

[ 13 ]

[ 14 ]