RAMLとは
RAMLとはRESTful API Modeling Languageの略でYAMLベースのRESTful APIを設計するためのモデリング言語です。
前提
基本的にRESTful APIの利用方法を知っていること : リクエストの送信およびレスポンスの処理を理解し、RESTful APIのコンポーネントの定義の仕方を理解している。
最初に
まず、いくつかの基本情報をテキストエディタで書き始めます。APIのRAML定義を推奨する拡張子である .ramlをつけたテキストファイルを保存します:
#%RAML 1.0
---
title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1
リソースの入力
APIコンシューマがどのようにAPIを利用するかを思い出し、以下の3つのリソースをルートに入力します:
/users:
/authors:
/books:
ネストされたリソースは特定のサブセットを呼び出して、リソースを絞り込む際に便利です。例えば :
/authors:
/{authorname}:
メソッドの入力
ここでは利用可能にしたリソースに対して、開発者にして貰いたい事を決定することを考える所から始めます。まずは4つの一般的なHTTP動詞について確認します:
GET — リクエストURIに定義された情報を取得します。
PUT — アドレスされた集合を置き換えます。 オブジェクトレベルではそれを作成もしくは更新します。
POST — 新しいエントリーをコレクション内に作成します。このメソッドは一般的にはオブジェクトレベルでは使用されません。
DELETE — リクエストURIに定義された情報を削除します。
ネストされたメソッドは、リソース下で開発者にそれらのアクションを許可します。注意点としてRAML API定義のメソッドでは小文字を使用する必要があります:
/books:
get:
post:
put:
URIパラメータの入力
私たちが定義したリソースはより小さな関係するオブジェクトのコレクションです。 優秀なAPIデザイナーであるあなたは、開発者がこれらのより粒度の小さなオブジェクトに対して処理できる事を最も望むだろうと考えます。上のネストされたリソースの例を覚えていますか？この例では /authors は {authorName} によって参照される特定の著者の集合で構成されています。これはRAMLでは周囲を中括弧で囲ったURIパラメータで表します。
/books:
/{bookTitle}:
ではリソースの固有の細かい粒度のオブジェクトに対してAPI仕様を反映させてみましょう:
/books:
get:
put:
post:
/{bookTitle}:
get:
put:
delete:
/author:
get:
/publisher:
get:
クエリパラメータの入力
ここまでよくできました！ それでは、APIによりパワフルな処理を可能にしていきましょう。既にオブジェクトベースのURIパラメータによって構成された、コレクションのリソースタイプがあります。しかしあなたは開発者がコレクションをフィルタリングできるようにしたいと考えます。クエリパラメータはこれを実現するための良い方法です。
いくつかのクエリパラメータを books のGETメソッドに追加する所から始めます。これは本の出版された年などの特定の特性を定義できます:
/books:
get:
queryParameters:
author:
publicationYear:
rating:
isbn:
put:
post:
クエリパラメータは アクセストークンなどAPIコンシューマのリクエストを処理するためにサーバが要求するものでもあります。多くの場合、コレクションやレコードを更新するにはセキュリティ認証が必要です。
特定のタイトルのPUTメソッドの下にアクセストークンクエリパラメータをネストします:
/books:
/{bookTitle}
get:
queryParameters:
author:
publicationYear:
rating:
isbn:
put:
queryParameters:
access_token:
APIのリソースおよびメソッドは、多くのクエリパラメータを持っていることがよくあります。それぞれのクエリパラメータは、それをさらに定義するための任意の数のオプション属性を持つことができます。クイックリファレンスガイドには完全なリストが含まれています。
では、上記で定義したそれぞれのクエリパラメータに属性を定義します。可能な限りいつものように説明を追加するようにします:
/books:
/{bookTitle}
get:
queryParameters:
author:
displayName: Author
type: string
description: An author's full name
example: Mary Roach
required: false
publicationYear:
displayName: Pub Year
type: number
description: The year released for the first time in the US
example: 1984
required: false
rating:
displayName: Rating
type: number
description: Average rating (1-5) submitted by users
example: 3.14
required: false
isbn:
displayName: ISBN
type: string
minLength: 10
example: 0321736079
put:
queryParameters:
access_token:
displayName: Access Token
type: string
description: Token giving you permission to make call
required: true
レスポンスを入力
レスポンスは 1つ以上のHTTPステータスコードとマッピングする必要があり、それぞれのレスポンスはdescriptions(概要),examples(例),もしくはschemas(スキーマ)が含まれます。スキーマについては200のチュートリアルで説明されています。
/books:
/{bookTitle}:
get:
description: Retrieve a specific book title
responses:
200:
body:
application/json:
example: |
{
"data": {
"id": "SbBGk",
"title": "Stiff: The Curious Lives of Human Cadavers",
"description": null,
"datetime": 1341533193,
"genre": "science",
"author": "Mary Roach",
"link": "http://e-bookmobile.com/books/Stiff",
},
"success": true,
"status": 200
}
おめでとうございます！ これであなたは最初のAPI定義をRAMLで記述しました。
参照：
https://raml.org/developers/raml-100-tutorial
https://mitch-oka.medium.com/raml-100%E3%83%81%E3%83%A5%E3%83%BC%E3%83%88%E3%83%AA%E3%82%A2%E3%83%AB%E6%97%A5%E6%9C%AC%E8%AA%9E%E8%A8%B3-fab9e509fbb
