RAML 100チュートリアル日本語訳

8 min readMar 25, 2020

RAMLとはRESTful API Modeling Languageの略でYAMLベースのRESTful APIを設計するためのモデリング言語です。
Open API Initiativeが提供するOASと比べて、人間が理解しやすい構文であったり、再利用性を高めるための仕組みが用意されており、API仕様の定義のみならず、APIのモデリングを手助けする仕様になっています。

Anypoint PlatformもAnypoint Studio7.4よりOASをネイティブサポートしたため、Anypoint Platformを超えてAPIを対外的に公開・共有していく際にはOASが今後は利用されていくようになると思われますが。RAMLも人間がAPI設計を行う上では魅力的な言語の一つです。

そこで今回はRAML.orgに用意されているRAMLチュートリアルの前半部分(RAML 100 Tutorial)を翻訳してみました。
https://raml.org/developers/raml-100-tutorial

後半部分のRAML 200チュートリアルの翻訳はこちら
https://medium.com/@mitch_oka/54dccf9c1cf9

RAML 100 チュートリアル

目的: BookMobileの基本的なAPIをデザインすることでRAMLの基本を学びます。

はじめに

このチュートリアルはAPIのデザインを概念化し、RESTfulなAPIのためのモデリング言語であるRAMLに記述するのを助けます。

前提

基本的にRESTful APIの利用方法を知っていること : リクエストの送信およびレスポンスの処理を理解し、RESTful APIのコンポーネントの定義の仕方を理解している。

最初に

あなたはBookMobileというスタートアップのAPIデザイナーです。今は事業計画とスケーリング計画を策定したところで、Ashton Kutcherがエンジェル投資家です。あなたはAPIデザインと開発者が作る実装を資産化したいと考えています。それにはRESTful APIがその一つの解決策であるため、まずは仕様を書き始める事にしました。

まず、いくつかの基本情報をテキストエディタで書き始めます。APIのRAML定義を推奨する拡張子である .ramlをつけたテキストファイルを保存します:

API仕様のルート(もしくはトップ)に入力した内容がAPIのすべての部分に適用されます。これは後ほどAPIを構築するパターンを理解したときに非常に便利だと実感できると思います。baseURIはすべてのコールで利用されるので、それが美しく簡潔であることを確認してください。

リソースの入力

優秀なAPIデザイナーになるには、APIコンシューマがどのようにAPIを利用するかを考慮することが重要です。特に重要な理由は、様々な意味でAPIデザイナーが”消費”をコントロールすることになるためです。例としてBookMobile APIの機能を検討してみましょう。あなたはユーザーが読んだ実績やお気に入りを追跡できるようにしたいと考えています。ユーザーは新しい本を見つけられ、お気に入りの著者の他のタイトルを探すことができます。これを行うには、色々なコレクションをリソースとして定義する必要があります。

APIコンシューマがどのようにAPIを利用するかを思い出し、以下の3つのリソースをルートに入力します:

注意点としてこれらの全てのリソースはスラッシュ(/) で始まります。 RAMLでは、これがリソースを示す方法です。全てのメソッドおよびパラメータはこれらのトップレベルリソースに属し、そのリソースに基づいて動作します。され、これらのリソースはそれぞれ個々のオブジェクト(特定の著者、本、およびユーザーなど)のコレクションなので、コレクションを記述するために、いくつかのサブリソースを定義する必要があります。

ネストされたリソースは特定のサブセットを呼び出して、リソースを絞り込む際に便利です。例えば :

これによりAPIコンシューマは主要リソースおよびそのネストされたリソースと対話できます。たとえば、http://api.e-bookmobile.com/authors/Mary_Roach へのGETリクエストは、科学執筆者かつユーモリストであるMary Roachの詳細を返します。では、開発者およびAPIコンシューマーに何をしてもらいたいかを考えてみましょう。

メソッドの入力

ここでは利用可能にしたリソースに対して、開発者にして貰いたい事を決定することを考える所から始めます。まずは4つの一般的なHTTP動詞について確認します:

GET — リクエストURIに定義された情報を取得します。

PUT — アドレスされた集合を置き換えます。オブジェクトレベルではそれを作成もしくは更新します。

POST — 新しいエントリーをコレクション内に作成します。このメソッドは一般的にはオブジェクトレベルでは使用されません。

DELETE — リクエストURIに定義された情報を削除します。

BookMobile APIの各リソースに任意のレベルで任意の数のメソッドを追加できます。しかし、各HTTPメソッドはリソースごとに1回しか使用できません。よく言われる事ですが、GETを使いすぎないように注意します。この例では、開発者がコレクションレベルで作業できるようにします。例えばAPIコンシューマはコレクションから本を取得(GET), 本を追加 (POST), もしくはライブラリ全体を更新(PUT)を行えます。そしてもっとも高いレベルでの情報の削除をさせたくありません。では /book リソースの作成にフォーカスしてみましょう。

ネストされたメソッドは、リソース下で開発者にそれらのアクションを許可します。注意点としてRAML API定義のメソッドでは小文字を使用する必要があります:

URIパラメータの入力

私たちが定義したリソースはより小さな関係するオブジェクトのコレクションです。優秀なAPIデザイナーであるあなたは、開発者がこれらのより粒度の小さなオブジェクトに対して処理できる事を最も望むだろうと考えます。上のネストされたリソースの例を覚えていますか？この例では /authors は {authorName} によって参照される特定の著者の集合で構成されています。これはRAMLでは周囲を中括弧で囲ったURIパラメータで表します。

したがって、ネストされたリソースへのリクエスト作る場合、Mary Roachの書籍である”Stiff”のURIは http://api.e-bookmobile.com/v1/books/Stiff のようになります。
ではリソースの固有の細かい粒度のオブジェクトに対してAPI仕様を反映させてみましょう:

クエリパラメータの入力

ここまでよくできました！それでは、APIによりパワフルな処理を可能にしていきましょう。既にオブジェクトベースのURIパラメータによって構成された、コレクションのリソースタイプがあります。しかしあなたは開発者がコレクションをフィルタリングできるようにしたいと考えます。クエリパラメータはこれを実現するための良い方法です。

いくつかのクエリパラメータを books のGETメソッドに追加する所から始めます。これは本の出版された年などの特定の特性を定義できます:

クエリパラメータはアクセストークンなどAPIコンシューマのリクエストを処理するためにサーバが要求するものでもあります。多くの場合、コレクションやレコードを更新するにはセキュリティ認証が必要です。

特定のタイトルのPUTメソッドの下にアクセストークンクエリパラメータをネストします:

APIのリソースおよびメソッドは、多くのクエリパラメータを持っていることがよくあります。それぞれのクエリパラメータは、それをさらに定義するための任意の数のオプション属性を持つことができます。クイックリファレンスガイドには完全なリストが含まれています。

では、上記で定義したそれぞれのクエリパラメータに属性を定義します。可能な限りいつものように説明を追加するようにします:

PUTコールをする場合、URIは http://api.e-bookmobile.com/books/Stiff?access_token=ACCESSTOKEN のようになります。

レスポンスを入力

レスポンスは 1つ以上のHTTPステータスコードとマッピングする必要があり、それぞれのレスポンスはdescriptions(概要),examples(例),もしくはschemas(スキーマ)が含まれます。スキーマについては200のチュートリアルで説明されています。

おめでとうございます！これであなたは最初のAPI定義をRAMLで記述しました。