Edited at

RAMLとOASとの使い分けメモ

More than 1 year has passed since last update.


OASとRAML

RESTful API定義の記述言語にはいくつか種類がありますが、GoogleやIBM、Microsoft、Red Hatなどの大手が参加するOpen API Initiativeが推進するSwaggerをベースにした OAS (Open API Specification) がデファクトスタンダードになりつつあります。

OpenAPI_Logo_Pantone-1.png

https://www.openapis.org/

一方、別のAPI定義であるRAML(RESTful API Modeling Language)の推奨しているRAML Workgroupというのがありますが、その中でも中心的な存在であるUri SaridがCTOを務めるMuleSoftがOpen API Initiativeに加盟したことによって、RAMLをやめてOASに一本化するのか?どうなるの?と疑問に思って調べてみました。

結果、Uri SaridのBlogポストによると、結論両方使うべき(which should I choose? The answer is: both!)ということでした。

ramllogo.png

Open API and RAML: Better Together

https://blogs.mulesoft.com/dev/api-dev/open-api-raml-better-together/


OASとRAMLの使い分けは?

OAS_RML_500x215.png

なぜ両方使い分けるべきなのかということの背景としては、OASはRESTful APIのための汎用定義言語であってAPIの定義とより広範囲なAPI仕様の共有に向いているもので、一方のRAMLはその名の通りAPIモデリング言語であるからだ、ということのようです。

RAMLのOASと比べた利点として、開発者(人間)がAPIを簡単かつ効率的にモデリングできる点や再利用可能なパターンやコンポーネントが表現できる点をあげています。こちらの動画でも同様にRAMLとOASについて違いとしては同様のことが解説されていました。

MuleSoft CONNECT18 - Build Consistently Great APIs using API Specs

https://videos.mulesoft.com/watch/wdnct8v6daSZudFTmt57UMs

RAML_OAS.png

またAMF(AML Modeling Framework)というOASとRAML両方に対応した (というかYAML/JSONベースのドキュメントの読み書きを行える)メタフレームワークを提供しており、これを使うえばOAS <-> RAMLの相互変換が可能だということです。モデリング言語RAMLを使ってAMFを使ってできた成果物がOASといった所でしょうか。

他にも https://github.com/mulesoft/oas-raml-converter に OAS <-> RAMLのコンバータは用意されている様なので、相互変換という観点では問題はないようです。


結論

つまり(Uri Sarid曰く、ですが)


  • APIを再利用性のある箇所を抽出するなど、しっかりモデリングしながら設計したい場合 -> RAML

  • 設計したAPI仕様を外部も含めてより広く公開したい場合 -> OAS (もしくはRAMLをOASへ変換して公開)

というのが推奨のようです。

まぁRAMLの方が優れてるなら世の中みんながRAMLを使えばええやん?と思ったりもしますが、周辺のツールなどを含めたエコシステムの成熟などを考えるとOASは汎用性という点では一日の長があるので、そこを踏まえての現時的な判断という事なのかもしれません。