APIを定義する時に、YAMLとRAMLなど、ややこしい用語がたくさんあります。この2つの用語は、非常に類似したものですが、大きな違いがあります。本文では、YAMLとRAMLとの違いを解説した上、RAMLをより汎用されているYAMLに変換する方法を皆さんに紹介しようと思います。
YAMLとRAMLについて
YAMLとは、YAML Ain't Markup Languagの略語として再帰的頭字語を意味して、データをシリアライズするためのテキストベースのマークアップ言語です。YAMLは、配置ファイルとAPI記述によく使われています。例えば、OpenAPIとSwaggerともYAMLフォーマットをデフォルトの記述言語として使用しています。
その一方で、RAMLは、YAML言語をベースにして、REST APIを定義するためだけに作られた言語になります。一見すると、YAMLに非常に類似しているものになりますが、実際に大きな違いあります。RAMLフォーマットは、APIの設計とモデル構築に取り組んでいる言語です。より簡単に言うと、RAMLはAPIのエンドポイントの記述に利用される事が可能です。
YAMLとRAMLとの違い
上記の概念から見ると、RAMLはYAMLに基づく言語として、全てのRAMLもYAMLになっていますが、全てのYAMLはRAMLになっているわけではありません。
RAMLはYAMLの表記力と拡張性を利用しつつ、API定義専用に特化させたマークアップ言語だと主張しているにも関わらず、それ以外の場合で利用することもできます。その一方で、RAMLをOpenAPIとSwaggerのドキュメントでのYAML記述に比較すると、OpenAPI仕様を記述しているYAMLは、APIとの契約のようなもので、APIに対する期待を定義するものになります。
要するに、APIのライフサイクル全体でRAMLとYAMLが適用されます。ただし、RAMLはAPIライフサイクルの初期段階であるモデル構築に重点を置いているため、APIの開発が進むにつれて、RAMLを他のフォーマットに変換する必要があるかも知れません。OpenAPIの仕様は、一番汎用されているAPI仕様になりますので、最終的にRAMLをYAMLに変換する必要がある場合が多いのでしょう。
YAMLとRAMLにも互換：Apidog
YAMLとRAMLの違いなんだとしても、両者ともAPI記述のためによく使われる言語になります。YAMLとRAMLのいずれかのフォーマットを使用して記述しているAPIなら、Apidogはそれに完璧に対応できます。
ApidogはYAMLとRAMLフォーマットのAPIをインポートすることをサポートしているので、YAMLとRAMLフォーマットのAPIを完全に解析して、APIのデータを完全にApidogにインポートしてテストできます。もちろん、Apidogを使用すると、コードが全く入らなくて、直感的な操作でAPIを設計したりすることもできます。
ステップ⒈プロジェクトの設定を開き、「データをインポート」をクリックすると、「OpenAPI/Swagger」か「RAML」を選択して、YAMLかRAMLファイルをApidogにドラッグします。
ステップ⒉Apidogは、YAMLかRAMLファイルを解析するので、データの保存先を選択すると、「確認」ボタンをクリックするだけで、APIを簡単にApidogにインポートできます。
そして、ApidogというAPI管理ツールを使って、当該APIをテストしたりすることができるようになりますし、APIリクエストを送信して直ちに内蔵のモックサーバーを使って仮のレスポンスデータを取得することもできます。
