RAMLとは？その書き方を解説

RAML(Restful API Modeling Language) は、RESTful APIを定義するためのYAMLベースのマークアップ言語です。Restful APIがどんどん主流になっている今、RAMLをマスターする必要があるのでしょう。本文では、RAMLを詳しく紹介した上、RAMLの書き方も一緒に皆さんに解説していきたいと思います。

RAMLとは

RAML(Restful API Modeling Language) は、RESTful APIを定義するためのYAMLベースのマークアップ言語です。RAMLの主な特徴は以下の通りです:

YAML形式で記述するので、人が読みやすく機械が解析しやすい
HTTPメソッド、URIパラメータ、リクエスト/レスポンスのスキーマ等を定義できる
APIのドキュメントを自動生成できる
モックサーバを自動生成でき、APIの検証がしやすい
多数の言語やフレームワークで利用できるライブラリがある

RAMLは、REST API開発者にとって重要なツールの1つとして知られています。RAMLを使うことで、APIの設計からドキュメント、テスト、実装までを効率的に行うことができます。

RAMLの読み方

多くの利用者は、RAMLの読み方は何かが分かっていません。それでは、RAMLをどうやって読めばいいですか？実際には、RAMLについて、事前に約束されている読み方はありませんが、基本的には「アール・エイ・エム・エル」になりますね。また、YAMLを「ヤメル」か「ヤムル」と読みますので、RAMLの読み方も「ラメル」になれるのでしょう。

RAMLとYAMLとの違い

YAMLとは、YAML Ain't Markup Languagの略語として再帰的頭字語を意味して、データをシリアライズするためのテキストベースのマークアップ言語です。RAMLは、YAML言語をベースにして、REST APIを定義するためだけに作られた言語になります。

要するには、RAMLとYAMLは非常に類似しているものです。全てのRAMLもYAMLになっていますが、全てのYAMLはRAMLになっているわけではありません。RAMLはYAMLの表記力と拡張性を利用しつつ、API定義専用に特化させたマークアップ言語ということです。

わかりやすく解説：RAMLの書き方

RAMLはYAML形式で記述するので、人が読みやすくて機械が解析しやすい構造になりますので、書き方も他の言語より比較的に簡単になります。RAMLでAPIを定義する基本的な書き方は以下の通りです。

ベースとなるAPIの情報を記述

#%RAML 1.0
title: Sample API
version: v1
baseUri: https://example.com/api

title: APIのタイトル
version: バージョン
baseUri: APIのベースURI

リソースを定義

/users:
  get:
    description: Get users
    responses:
      200:
        body:
          application/json:
            type: User[]

/users: エンドポイントのパス
get: HTTPメソッド
description: 説明文
responses: レスポンスの定義
body: レスポンスボディの定義

型定義

types:
  User:
    type: object
    properties:
      id: string
      name: string

types: 型の定義セクション
User: 型の名前
properties: プロパティの定義

このように、APIのエンドポイント、データ型、レスポンスをYAML形式で定義していきます。

RAMLには他にも多くの拡張機能があり、大規模なAPIを定義できます。

RAMLのサンプル

それでは、上記のRAMLの書き方を元にして、RAMLのサンプルコードを皆さんに示します。例えば、簡単なTODO APIの定義例を行うために、RAML書き方のサンプルは次のようになります：

#%RAML 1.0
title: TODO API
version: v1
baseUri: https://example.com/api

/todos:
  get:
    description: Get all todos
    responses:
      200:
        body:
          application/json:
            type: Todo[]
            
  post:
    description: Create a new todo
    body:
      application/json:
        type: Todo
    responses: 
      201:
        body:
          application/json:
            type: Todo
            
types:
  Todo:
    type: object
    properties:
      id: integer
      title: string
      completed: boolean

このAPIでは、/todosエンドポイントに対して、次の操作を行なっています：

GETメソッドで全てのTODOを取得
POSTメソッドで新規TODOを作成

RAMLによってリクエスト、レスポンスのスキーマとTodoオブジェクトの定義が記述されています。このRAMLファイルからドキュメントやモックサーバも自動生成できるので、API設計がスムーズにできます。

RAMLのGUIツールおすすめ：Apidog

Webアプリ開発中に、API定義のために、RAMLは非常に広く使われています。RAMLフォーマットで記述しているAPIなら、Apidogはそれに完璧に対応できます。

button

ApidogはRAMLフォーマットのAPIをインポートすることをサポートしているので、RAMLフォーマットのAPIを完全に解析して、APIのデータを完全にApidogにインポートしてテストできます。もちろん、Apidogを使用すると、コードが全く入らなくて、直感的な操作でAPIを設計したりすることもできます。

ステップ⒈プロジェクトの設定を開き、「データをインポート」をクリックすると、「RAML」を選択して、RAMLファイルをApidogにドラッグします。

ステップ⒉ここでRAMLファイルが解析され、データの保存先を選択すると、「確認」ボタンをクリックするだけで、それを簡単にApidogにインポートできます。

そして、ApidogというAPI管理ツールを使って、当該APIをテストしたりすることができるようになりますし、APIリクエストを送信して直ちに内蔵のモックサーバーを使って仮のレスポンスデータを取得することもできます。

button