1

リソースの文書化に W3C XML スキーマ (XSD) を使用しています。現在、XML 表現は少数のリソースで返されます。リソースの 1 つでの POST 操作には、クライアントからの XML が必要です。このリソースの応答は XML です。私の質問は次のとおりです。

a) リソースのリクエスト (POST)、レスポンスを処理するために 1 つの XSD を作成する必要がありますか?

b) 単一の XSD が使用されている場合、リクエスト (POST) とレスポンスをどのように区別すればよいですか? 1つの考えが取り囲んでいます：

<stream>
  <request>
    <items>xxx</items>
  </request>
  <response>
    <stuff>xxx</stuff>
  </response>
</stream>

問題は、リクエスト/レスポンス タグが RPC スタイルのアプローチを反映しているのではないかと心配していることです。

c) POST 操作に関して、XML が必要であり、POST 操作中にのみ許可されることをクライアントに通知したいと思います。この要件に違反している場合、私の最善の選択肢は 400 の不正な要求を返すことだと思いますか? それを超えて、XSDに関する私の唯一のオプションは、「コメントを介して要件を文書化する」ことだと思いますか? コメント以外に考慮すべき XSD 設計オプションの感触を得ようとしています。もちろん、1 つの XSD での課題は、クライアントからの XML を必要としない GET 操作への応答です。クライアントは、XML 内の POST コンテンツを「無視」する必要があります。

前もって感謝します

4

1 に答える 1

0

a) 1 つの XSD を作成し、その XSD 内で複数のタイプを定義することは問題ありません。単一の XSD で要求/応答のペアを定義することは、私には理にかなっているように思えます。XSD の消費者またはユーザーを念頭に置いてください。それは誰でしょう？API のユーザーがその XSD を使用してアプリを構築することを期待していますか?それとも、受信したリクエストを検証するためにサーバー (受信) 側でのみ使用されますか?

多くの場合、REST API で交換されるメッセージは、スキーマ ドキュメントで正式に定義されていません。代わりに、それらは HTML ページに文書化され、企業は API テスト ページを提供します。そこでは、リクエストとレスポンスの例を確認できます。これは、API を文書化するための非常に実用的な方法です。この例については、https://api.stackexchange.com/docs/answersを参照してください。

b) リクエストとレスポンスを区別するには、XSD で異なる要素タイプを使用すると思います。多分私は質問を理解していません。

c) 400 を返すことは完全に合理的です。要求が間違ったコンテンツ タイプである場合、XML ドキュメントが含まれていない場合、または XML ドキュメントが必要なスキーマに準拠していない場合です。400 を返す場合は、メッセージ本文と、詳細情報を提供する XML ドキュメントも返すことをお勧めします。

<response> 
  <error>
    <code>101.4.c</code>
    <description>your request did not include an XML document</description>
    <link>http://example.com/errorinfo?code=101.4.c</link> 
  </error>
</response>

REST API 設計の詳細については、http://dinochiesa.net/?p=192を参照してください。

于 2012-06-30T02:40:00.713 に答える