web-services - 機械可読形式の REST サービスの例

Question

私が目にするほとんどの REST インターフェイスは、URL、メソッド、受け入れられた入力、および返された結果を説明する単純な Web ページで記述されています。たとえば、Amazon S3やTwitter APIドキュメントなどです。

Amazon や Twitter では、人間が読める形式で十分なようです。しかし、REST API を機械可読形式で記述している企業はありますか? はいの場合、どれですか？

WSDL 2.0 クレームはREST を記述することができます。WADLは、REST サービスを記述するために明示的に作成されます。WSDL 2.0 と WADL はどちらも、従う傾向がかなり小さいようであり、記述ドキュメントを作成して維持する努力に対する見返りはほとんどないようです。実際の例を特定することで、基本的にこの仮定を検証または否定することができます。

サービスの記述に WSDL/WADL を使用していますか? 他のサービスを利用するために WSDL/WADL に依存していますか? 選択したツールは、現時点でいずれかをサポートしていますか? 広く使用されている使用可能な REST サービスの例で、詳細が機械可読形式で示されているものはありますか?

Answer 1

はい、そうすべきです。WADL をサポートする一連のツールを使用して、クライアント コード、テスト、およびドキュメントを生成できます。いくつかの例はここにあります。また、WSDL 2.0 ではなく WADL に固執する必要があると思います。実際、WADL では、WADL XML 構文を使用するだけで、ドキュメンテーション ページでユーザーに表示される内容を正確に記述できます。ところで、これが、WADL 用の XSLT ベースのドキュメント ジェネレーターを簡単に作成できる理由です。

Answer 2

以下はあくまでも個人的な意見です。

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

理由は簡単だと思います。複雑な地図をブラウジングするよりも、サイトをさまよって戦略的に配置されたボタンを押す方が、はるかにやりがいがあることが多いからです。

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

Answer 3

WSDL (および WADL も同様) の最も一般的な使用法は、コード生成です。確かに開発のスピードアップには役立ちますが、単純な古いドキュメントに取って代わるものは何もありません。機械用ではなく、人間用です。

Answer 4

ここにはニワトリ/卵現象があります。WADL は、生成または消費するツールがなければ役に立ちません。サイトが WADL を公開しない限り、ツールは役に立ちません。等

私にとっては、Amazon モデルは問題なく機能します。視聴者に応じて、サンプル ダイアログの切り取り (ネットワーク上では request1 はどのように見えるか、応答 1 は同じ、次に要求 2、応答 2 など) やさまざまなコードを含む、サンプルを作成する努力に対してより多くの見返りを得ることができます。あなたにとって重要な言語。機械可読な定義に移動したい場合は、XML メッセージ形式であれば XSD を使用できます。明らかにこれはWADLではありませんが、英語の説明と相まって、開発者に少し余分なユーティリティを提供する可能性があります.

Answer 5

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

REST のポイントは、API が比較的シンプルで理解しやすいことです。自然言語はこれに適しています。

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

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

多くの場合、REST 動詞の機能と URI を英語で記述した方が簡単です。JSON (または YAML または JAXB) を介してマーシャリングされた型をソース コードとして送信します。これは完全な機械可読 API であり、メッセージ オブジェクト クラスの実際の作業ソースです。