Что такое «RAML»
Когда команда сайта и команда мобильного приложения договариваются об API, письма и таблицы быстро устаревают. Нужен один файл, который читают и люди, и программы. RAML предложили в 2013 году компания MuleSoft и партнёры, версия 1.0 вышла в 2016-м. Название расшифровывается как RESTful API Modeling Language — язык моделирования API в стиле REST.
Как выглядит описание
Файл пишется на YAML и начинается со строки с версией. Ресурсы задаются путями, внутри — методы, параметры и ответы. Типы данных объявляются один раз и переиспользуются:
#%RAML 1.0
title: Orders API
version: v1
baseUri: https://api.example.ru/{version}
types:
Order: {properties: {id: integer, status: string}}
/orders/{orderId}:
get:
responses:
200:
body:
application/json: {type: Order}
Прочитать это можно без подготовки: запрос GET /orders/15 вернёт JSON с номером и статусом заказа. Вложенность ресурсов повторяет структуру адресов, а общие куски выносятся в трейты и типы ресурсов, чтобы не повторять одно и то же для каждого метода.
RAML и OpenAPI
Задачу описания REST API решает и спецификация OpenAPI, бывший Swagger. Какое-то время форматы конкурировали, но OpenAPI стал отраслевым стандартом: под него больше генераторов, редакторов и готовых интерфейсов документации. В 2017 году MuleSoft сама вошла в OpenAPI Initiative. RAML по-прежнему встречается в проектах на платформе MuleSoft и в API, описанных несколько лет назад. Новые описания чаще делают в OpenAPI, а для старых есть конвертеры.
Подход «сначала контракт»
Главная польза таких языков не в формате, а в порядке работы. Сначала команды согласуют описание, затем фронтенд работает с заглушкой, сгенерированной из файла, а бэкенд пишет реализацию. Тесты сверяют реальные ответы с описанием. Ошибки вроде «в документации поле называется price, а приходит cost» ловятся до выхода в продакшен, а не на стороне клиента.
Связанные термины
Обновлено: 10 октября 2026

