RESTful APIの設計、開発、ドキュメント管理を手助けする「RAML」とは：APIを効率的に管理できる記述言語

　RAMLはYAML（YAML Ain't Markup Language）に基づいている。YAMLは、「Kubernetes」にデプロイされるようなワークロードをサポートするための構成ファイルの記述によく使用されるデータシリアライズ言語だ。YAMLを知っていれば、RAMLコードには見覚えがあるはずだ。ただし、YAMLではさまざまな構成を記述できるのに対し、RAMLはAPIの記述に特化して設計されている点が大きく異なる。

　RAMLの仕様言語としての使いやすさは、APIを記述する柔軟性だけでなく、その記述の一貫性にもある。RAMLで提供される構造によって標準化が促されるため、開発者はAPIの機能をマシンにも人間にも分かりやすく、読みやすい形式でまとめたコードを生成できる。

開発者やアーキテクトがRAMLを使用する例

　開発者やアーキテクトは、次の目的においてRAMLを使用できる。

• APIの設計時にAPIが機能する仕組みを説明する
• 開発したAPIの仕組みをドキュメントにする
• APIの仕組みを記述したRAMLコードへの変更を追跡して、時間の経過とともにAPIに加えられた変更を管理する

　APIの機能を記述する方法は多岐にわたるため、APIの仕組みの説明に広い範囲で矛盾が生じたり、効果的な説明ではなかったりすることがある。そうした状況を減らすためにRAMLが導入されている。例えば、APIはさまざまなタイプのクエリを受け取り、異なるMIMEタイプのデータをフォーマットし、応答コードを生成する。この多様性により、あるAPIでは機能する記述形式が、別のAPIでは機能しない可能性がある。

　APIは一様なものでないため、開発者はAPIのドキュメントを作成する際、機能をありきたりの表現で説明しなくてはならないことが多い。つまり、開発者はマシンコードではなく、自然言語でAPIのドキュメントを作成することになる。この種のAPIドキュメントの作成には時間がかかり、構造に一貫性がない。そのため、ドキュメントをプログラムで処理するのは難しい。

　こうした課題に対処するため、RAMLはREST APIに存在する可能性のある全ての属性を予測し、コードを使って各属性を定義する方法を提供する。RAMLを使えば、従来のようなドキュメントを作成せずに、一貫性のある表現でAPIを説明できる。

RAMLの制約

　RAMLはAPIの作成と管理を必要とする開発者にとっては強力なツールだが、幾つか制限もある。

• RAMLでは、HATEOAS（Hypermedia as the Engine of Application State）によって駆動されるAPIは明示的にはサポートされない。RAMLをHATEOASフレンドリーにする方法を考案している開発者もいるが、それでも記述上の問題は生じる
• RAMLではコードを再利用する機能も限定的で、API管理ツールとの互換性も特定のツールに限られる。ユーザーのニーズに応じて、オープンソースの「Swagger」などのツールをAPIの記述に使用する開発者もいる

RAMLを最大限に活用するためのベストプラクティス

　RAMLを最大限に活用するためのヒントとベストプラクティスを幾つか紹介する。

• 一貫性を保つ：RAMLはREST APIの記述をほとんど標準化している。ただし、コードの構造とファイル名はユーザーが決めなければならない。開発と保守には、一貫性の確保と体系化が重要になる
• 完全なコードにする：RAMLには、APIの記述にエラーメッセージの方式など、重要な情報が欠けているかどうかを知る方法がない。仕組み全体を記述し、APIの仕組みに関する情報を全て確実に含める必要がある
• コードのバージョンを管理する：時間の経過とともに変化するRAML仕様を自動的に追跡することで、APIの機能の進化も追跡できる
• コードを検証する：他のコードと同様、RAML仕様には、かっこや引用符の欠落などの誤解を招くエラーが含まれている可能性がある。RAMLはYAMLベースのため、YAMLコード検証ツールを使えばエラーを検出できる可能性がある