ヘッダーとは？

リクエストやレスポンスに付加情報を提供するための部分。データの種類、認証情報、リクエストの送信日時など、ペイロードには含まれないがその情報のメタ情報となるような種類の情報を保持。

URIパラメータとは？

URL内で特定のリソースを指定するために使われるもの。例えば、特定のユーザーの詳細情報を取得したい場合、そのユーザーのIDをURIパラメータとしてURLに含めることができます。上記のサンプルコードで言うと{userId}が該当。

RAMLとは？基本的な書き方と役割・使い方のコツを３分で解説

Q: ヘッダーとは？

リクエストやレスポンスに付加情報を提供するための部分。データの種類、認証情報、リクエストの送信日時など、 ペイロード には含まれないがその情報のメタ情報となるような種類の情報を保持。

RAML（RESTful API Modeling Language）とはAPIの設計を助けるツールのようなもので、その名の通りRESTful APIを設計するための言語です。

RAMLには、APIがどのように動作するか？といった詳細なルールや構造・APIを通じて送受信されるデータの型や形式・APIのエンドポイント（接続点）・そしてそれらが受け取る入力（インプット）と返す出力（アウトプット）の具体的な規格などが含まれます。以下が簡単なサンプルです。

#%RAML 1.0
title: Users API
version: v1
baseUri: http://example.com/api/{version}

/users:
  get:
    description: Get a list of users
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "users": [
                  {"id": 1, "name": "Alice"},
                  {"id": 2, "name": "Bob"}
                ]
              }

このページではRAMLの役割や、基本的な使い方・書き方を１からわかりやすく解説します。

RAMLとは？簡単に
RAMLの書き方

RAMLとは？簡単に

RAMLはAPIの「設計図」を作成する手助けをするツールだと言えます。

例えば建築家は、家を建てる前にどのように家が見えるか、どの部屋がどこにあるか、どんな機能を持つかを紙の上で詳細に描きますよね。この設計図があることで、建築現場の人々は正確に家を建てるためのガイドラインを持つことができ誤解や間違いを減らすことができます。RAMLもこれと同じで、APIを開発するための設計図としての役割を担います。

APIは家そのもの　→RAMLが家の設計図だとすると、APIは設計図に基づいて実際に建てられた家そのものに該当します。

ひとまずここでは、RAMLはAPIの設計図を作成するための言語であり、APIがどのように振る舞うべきか、どのようなデータを送受信するか、どのようにエラーを扱うかなど、具体的なAPIの骨格を表すものである！と覚えておきましょう。

RAMLの書き方

以下が冒頭にもお見せした簡単なRAMLのサンプルコードです。

このRAMLには何が書かれていて、どんな内容を定義しているのかを簡単に確認していきます。

#%RAML 1.0
title: Users API
version: v1
baseUri: http://example.com/api/{version}

/users:
  get:
    description: Get a list of users
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "users": [
                  {"id": 1, "name": "Alice"},
                  {"id": 2, "name": "Bob"}
                ]
              }

1. RAMLバージョンの指定

#%RAML 1.0：文書の先頭にこの行を書くことで使用しているRAMLのバージョンを宣言します。この宣言を行っておくことでパーサー（解析器）が適切に文書を読み込めるようになります。

#%RAML 1.0

2. APIの基本情報

title：APIの名前。
version：APIのバージョン。
baseUri：APIのベースとなるURL。URL中にはバージョン番号などの変数を埋め込むこともできます。

title: Users API
version: v1
baseUri: http://example.com/api/{version}

3. リソースとメソッド

リソース：APIで扱うデータの「種類」や「項目」を示します。通常、URLのパス（例：/users）で表されます。
メソッド：リソースに対する操作（HTTPメソッド）。get、post、put、deleteなどを定義します。

/users:
  get:

4. レスポンスとステータスコード

レスポンス：APIがどのようなデータを返すか、またはどのようなエラーが返るかを定義。
ステータスコード：レスポンスの種類を示すHTTPステータスコード（例：200、404、500）を指定。

/users:
  get:
    description: Get a list of users
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "users": [
                  {"id": 1, "name": "Alice"},
                  {"id": 2, "name": "Bob"}
                ]
              }

ザックリいえば、どんなURLにどんなリクエストを送ればどんなレスポンスが返ってくるか？を定義しているものがRAMLだと理解できればOK。他のプログラミング言語のように複雑な構文や条件分岐等も基本的にはなく、あくまでもドキュメンテーションとしての役割を果たしているものだと言えます。

上記の基本的な構造を理解しておくことで、あとは必要に応じて少しずつ拡張していけばOKです。

より実践的なRAMLの書き方

ここからはより実践的に、APIの機能を拡張しより詳細なAPI仕様を作成する方法をご説明していきます。

1. クエリパラメータの定義

APIエンドポイントにクエリパラメータを追加してユーザーが様々な形のリクエストを送れるようにすることもできます。例えば、ユーザーリストを取得する際に、年齢や職業でフィルタリングできるようにできたら便利です。

/users:
  get:
    description: Returns a list of users filtered by age and job
    queryParameters:
      age:
        description: Filter by age
        type: integer
        required: false
      job:
        description: Filter by job
        type: string
        required: false
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "users": [
                  {"id": 1, "name": "Alice", "age": 30, "job": "Engineer"},
                  {"id": 2, "name": "Bob", "age": 25, "job": "Designer"}
                ]
              }

クエリパラメータは、URLの一部としてデータを送る方法でWebサーバーに特定の情報を求める際に使われるのが一般的。クエリパラメータはURLの末尾に「？」記号の後に続けて記入され、キー（名前）と値の組み合わせで指定されます。複数のパラメータを送る場合は、「&」記号で区切ります。

例えば、年齢と職業でユーザー情報を絞り込む場合は以下のようなURLになります。

http://example.com/users?age=25&job=developer

この例では、age=25 と job=developer がクエリパラメータ。こうすることで年齢が25歳で職業が開発者（developer）のユーザー情報をWebサーバーにリクエストすることができるようになります。

2. ヘッダーとURIパラメータの追加

ヘッダーを使ってリクエストやレスポンスに追加の情報を含めることもできます。また、URIパラメータを利用して特定のリソースにアクセスする際の動的なパスを指定するようなことも可能です。

/users/{userId}:
  get:
    description: Returns a specific user by their ID
    uriParameters:
      userId:
        description: The user's ID
        type: integer
    headers:
      X-Request-ID:
        description: A unique identifier for the request
        type: string
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "id": 1,
                "name": "Alice",
                "age": 30,
                "job": "Engineer"
              }

Q ヘッダーとは？: A

リクエストやレスポンスに付加情報を提供するための部分。データの種類、認証情報、リクエストの送信日時など、ペイロードには含まれないがその情報のメタ情報となるような種類の情報を保持。

Q URIパラメータとは？: A

URL内で特定のリソースを指定するために使われるもの。例えば、特定のユーザーの詳細情報を取得したい場合、そのユーザーのIDをURIパラメータとしてURLに含めることができます。上記のサンプルコードで言うと{userId}が該当。

3. レスポンスとエラーハンドリングの定義

APIのレスポンスを詳細に定義することでエラー発生時のハンドリングを行うことも可能です。

/users/{userId}:
  get:
    responses:
      200:
        body:
          application/json:
            example: |
              {"id": 1, "name": "Alice", "age": 30, "job": "Engineer"}
      404:
        body:
          application/json:
            example: |
              {"error": "User not found"}

↑の例では、/users/{userId} エンドポイントに対するGETリクエストで、ユーザーIDに基づいてユーザー情報を取得する操作を定義。レスポンスとして成功時（200）はユーザーの情報を、失敗時（404）はエラーメッセージを返すことが示されています。

このようにレスポンスとエラーハンドリングを明確にすることで、APIの使用者はどんな結果を期待できるか、そして何か問題が発生したときにはどのように対応すればよいかを正確に理解することができるようになります。