RESTサービスを機械可読形式で記述する必要がありますか？

Question

私が見ているほとんどのRESTインターフェイスは、URL、メソッド、受け入れられた入力と返された結果を説明する簡単なWebページで説明されています。たとえば、Amazon S3またはTwitter APIのマニュアルです。

しかし、どうして私はAmazonやTwitterのために十分に優れているのかを解決する必要があります...それで、機械で読める形式でREST APIを記述する価値はありますか？そして、はいの場合はどちらですか？

WSDL 2.0クレームはcapable of describing RESTです。 WADLは、RESTサービスを記述するために明示的に作成されます。 WSDL 2.0とWADLの両方では、わずかなATFしかないように見えますが、記述文書を作成して維持する労力はほとんどかからないようです。私の援助は基本的に私の前提を検証したり否定したりすることです。

WSDL/WADLを使用してサービスを記述していますか？他のサービスを消費するためにWSDL/WADLに頼っていますか？選択したツールが現時点でどちらかをサポートしていますか？

Answer 1

次は私の個人的な意見です。

私はWADLは、HTMLページのサイトマップに似ていると思います。サイトマップは理論的には良い方法だと考えられていますが、めったに実装されず、人々によって使用されることはめったにありません。

私はその理由が単純だと思います。サイトを回り、戦略的に配置されたボタンを押すことは、しばしば複雑なマップをブラウズするよりも報酬が高くなります。

REST APIメソッドに正式な説明は必要ありません。したがって、APIが慎重に作成された場合、「家庭」のRESTfulリソースの戦略的に配置されたURIリンクをたどるだけで、すべてのリソースを簡単に見つけることができます。

Answer 2

機械可読のREST API定義の利点は何ですか？

RESTのポイントは、APIが比較的簡単でわかりやすいことです。これに対して自然言語がうまく機能します。

「API定義」と言ったときに「APIタイプ定義」を意味する場合は、メタデータを提供する際に価値があるかもしれません。ただし、これはAPI定義の1つのみです。

「機械で読み取り可能な」APIを使用すると、DRYの原則に違反してAPIソースコードを簡単に繰り返すことができます。

REST動詞が何をしているのか、URIが何であるのかについての英語の記述を書く方が簡単なことがよくあります。 JSON（またはYAMLまたはJAXB）を介してマーシャリングされた型をソースコードとして送信します。これは、メッセージオブジェクトクラスの実際の作業ソースである完璧なマシン読み取り可能なAPIです。

Answer 3

ここにはチキン/卵フェノネノンがあります。 WADLは、それを生成または消費するツールがなければ役に立たない。サイトがWADLを公開しない限り、ツールは役に立たない。

私にとって、Amazonモデルはうまく動作します。オーディエンスに応じて、サンプル・ダイアログ（サンプル1のようなもの、レスポンス1のもの、リクエスト2、レスポンス2などのようなもの）と、さまざまな種類のコードあなたにとって重要な言語。機械可読の定義に移動する場合は、XMLメッセージ形式の場合はXSDを使用できます。明らかに、これはWADLではなく、あなたの英語の記述と相まって、開発者のための少し余分なユーティリティを提供するかもしれません。

Answer 4

はい、そうです。WADLをサポートする一連のツールを使用して、クライアントコード、テスト、およびドキュメントを生成することができます。いくつかの例はhereです。また、WSDL 2.0ではなくWADLを使用することをお勧めします。これはあまり冗長ではなく簡単な方法（IMHO）です。実際、WADLでは、WADL XML構文を使用するだけで、ユーザーがドキュメントページに表示する内容を正確に記述します。それで、WADL用のXSLTベースのドキュメントジェネレータを書くのは簡単です。

Answer 5

WSDL（およびWADL）の最も一般的な使用方法は、コード生成です。これは確かに開発のスピードアップに役立ちますが、普通の古い文書を置き換えることはできません。人間のためであり機械のためではない。