関連リソースを持つRESTful API

Question

私はWCFサービスの上に座っている、最初の深刻なRESTful APIを設計中です。

などのリソースがあります。コンセント、スケジュール、仕事。スケジュールは常にアウトレットが所有し、スケジュールには0以上のジョブが含まれます。仕事がスケジュール通りである必要はありません。

私は、リソースがファイルシステム上でアドレス指定されるのと同じタイプの方法でアドレス可能であるべきであると考え続けています。これは私がURIのようなを持っていると思います意味します：

/outlets 
/outlets/4/schedules 
/outlets/4/schedules/1000/jobs 
/outlets/4/schedules/1000/jobs/5123 

物事はいえ、さまざまな状況の下でバックリソースをプルする方法を検討する際にかかわらず、厄介始めます。

例えば

（これは今、我々はそれがスケジュール上の背中の仕事をプルする2つの方法を持っている意味）

/outlets/4/jobs/85：私はスケジュールにない仕事をしたいです

/schedulesまたは

/outlets/ALL/schedulesは、他のより複雑な要件がたくさんありますが、私はあなたの要点を得ると確信している：私は、コンセントにかかわらず、すべてのスケジュールをしたいです。

ファイルシステムには、リソースをアドレッシングするための、論理的な方法があります。あなたは明らかにシンボリックリンクを作成して、私が記述したものに近いものを達成することができますが、それは面倒です。物事が少しでもより複雑に得ればそれも、このような日付でスケジュールを取得する機能を追加するなど、メシエされます：

/outlets/4/2016-08-29/schedules 

とクエリ文字列パラメータを使用せずに、私も、私は戻って要求するだろうかどうかはわかりませんスケジュールにないすべてのジョブ。 unscheduledがリソースではありませんので、以下は間違って感じている：だから

/outlets/4/unscheduled/jobs 

、私は、ファイルシステムタイプのアドレス指定は、サービスだけの最もシンプルなために仕事に行くされていることを考えるように来ている（私たちの基盤となるシステムは、エンティティタイプの数百を持っていますいくつかの非常に複雑な関係と膨大な数の操作があります）。

同じことをする方法が複数あると、混乱と乱雑な文書につながる傾向があり、避けたいのです。私は、使用して展開する必要がありますこれらの非常に単純なアドレス形式から

/outlets/4/schedules/1000/jobs/5123 
/outlets/4/jobs/5123 
/jobs/5123 

：以下第三のような - その結果、私は、ほぼ最小公分母と一緒に行くと非常に単純なアドレス形式を選択を選ぶことを強制していますクエリ文字列パラメータより複雑な何かを行うには、例えば：

/jobs?scheduleId=1000 
/jobs?outletId=4 
/jobs?outletId=4&fromDate=2016-01-01&toDate=2016-01-31 

これまでの考え方「何のドキュメントは必要ありません」から、それはしかしRESTモデルに対して起こっていると、このようなクエリ文字列パラメータは予測できないようにこれは感じています。

OK、クリーンでメンテナンス可能なAPIを手に入れようとしているフェンスの側にいるので、私は非常に単純なリソースアドレスを使用し、クエリ文字列パラメータ広範囲にわたり、良い文書を持っています。

とにかく、これは私が到着したはずの結論のようには感じません。どこが間違っていたのですか？

Answer 1

REST APIプログラミングの世界へようこそ。これらは、一般的な原則を特定の状況に適用しようとすると、私たち全員が直面する困難な問題です。あなたの質問には明確で簡単な答えはありませんが、役に立つかもしれないいくつかのヒントがあります。

まず、複雑な関係がある場合には、ファイルシステムのアドレス指定方法が問題になることは間違いありません。実際にという階層のある場合は、そのようなアドレッシングを設定したいだけです。

たとえば、すべてのジョブが1つのスケジュールに含まれていた場合は、schedules/{id}/jobs/{id}を参照して特定のジョブにアクセスすると意味があります。データストレージの観点から考えると、スケジュールごとにXMLファイルがあると想像できます。ジョブはそのファイル内の要素にすぎません。

しかし、この特定のケースのように、あなたのデータはの関係のように聞こえます。データ・ストレージの観点からは、各ジョブをデータベース表の行として表し、一部のジョブをいくつかのスケジュールに結びつけるために、いくつかの外部キー関係を確立します。アドレッシングスキームは、/jobsを最上位のエンドポイントにし、オプションのクエリ文字列パラメータを使用してスケジュールやアウトレットでフィルタリングするのが適切である場合には、これを反映する必要があります。

あなたは正しい軌道に乗っています。考慮すべきもう1つの事は、ODataです。ODataは、クエリ文字列パラメータを使用したフィルタリングなどの標準的な方法で基本的なREST原則を拡張しています。アドレス構文はちょっと「外に」感じますが、まっすぐなRESTが崩れ始める状況を処理するのは非常にうまくいきます。さらに標準化されているため、データレイヤーからODataエンドポイントに変換する、またはエンドポイントによって公開されるメタデータに基づいてクライアントサイドプロキシヘルパーを生成するツールなどがあります。

これはRESTモデルにも似ていますが、このようなクエリ文字列パラメータは予測できません。これまでのところ、 "no docs needed"というアイデアはありません。

ODataを使用する場合、その仕様はツールで作成されたメタデータと組み合わされ、ドキュメントになります。たとえば、jobには日付を表すdateというプロパティがあります。次に、OData仕様は、日付値のフィルター照会を表す方法を提供します。この情報から、消費者はフレームワークサーバー側を使用してハードパートを実行しているため、「うまく動作する」フィルタクエリを確実に作成できます。また、OData URLの仕組みを記憶していないと思われる場合は、好きな構文で適切なURLを生成できるように、選択した言語のクライアントプロキシを生成できます。