アプローチ2：正しい方法
最初の近似を突然見逃した場合は、 ここで見つけることができます。 この概算では、Web APIのリソースとメソッドへの一意のパスを構築する方法と、このパスとそのコンポーネントの外観に影響するアプリケーションのアーキテクチャ機能について個別に説明します。
海岸に立って考えること
バージョニング
遅かれ早かれ、既存のシステムは進化し始めます。開発、より複雑になり、拡張し、近代化します。 REST API開発者にとって、これは古いバージョンが実行されている間に新しいバージョンのAPIを起動する必要があるという事実に満ちています。 ここでは、システムの内部でのアーキテクチャの変更についてではなく、データ形式とそれらを使用した一連の操作の変更について説明します。 いずれにしても、バージョン管理は、ソースコードの元の組織と、原則としてURLの構築の両方で提供する必要があります。 URLに関しては、リクエストの宛先となるAPIのバージョンを指定する最も一般的な方法が2つあります。 パスexample-api.com/v1/の プレフィックスとサブドメインレベルv1.example-api.comでのバージョン管理。 ニーズとニーズに応じて、それらのいずれかを使用できます。
コンポーネントの自律性
複数のユーザーロールをサポートするWeb APIの複雑なシステムでは、多くの場合、それぞれが独自の範囲のタスクを提供する部分に分離する必要があります。 実際、各部分は独立したアプリケーションであり、異なる物理マシンおよびプラットフォームで実行できます。 APIの説明のコンテキストでは、サーバーがリクエストを処理する方法と、これに関与する力とテクノロジーは関係ありません。 クライアントにとって、APIはカプセル化されたシステムです。 それでも、システムのさまざまな部分、たとえば管理部分とユーザー部分など、まったく異なる機能を持つ場合があります。 そして、同じ方法で作業する方法論は、リソースが大幅に異なる可能性があるようです。 したがって、このような部分は、ドメインレベルadmin.v1.example-api.comまたはパスプレフィックスexample-api.com/v1/adminで分離する必要があります。 この要件は必須ではなく、システムの複雑さとその目的に大きく依存します。
データ交換フォーマット
私の意見では、最も便利で機能的なデータ交換形式はJSONですが、 XML 、 YAML、またはデータ型を失うことなくシリアル化されたオブジェクトを保存できる他の形式の使用を禁止するものはありません（入力用です）。 必要に応じて、APIに複数の入力/出力形式をサポートさせることができます。 HTTPリクエストヘッダーを使用して目的の応答形式Acceptを示し、 Content-Typeを使用してリクエストで送信されるデータの形式を示すだけで十分です。 別の一般的な方法は、たとえばGET /users.xmlのようにリソースURLに拡張子を追加することですが、この方法はURLが重くなり、すべての可能な操作よりもGET要求の可能性が高いという理由だけで、柔軟性と美しさが低下します。
ローカリゼーションと多言語
実際には、APIの多言語性は、多くの場合、サービスメッセージとエラーメッセージをエンドユーザーに直接表示するために必要な言語に翻訳することになります。 多言語コンテンツにも場所がありますが、異なる言語のコンテンツの保存と配信はより明確に区別する必要があります。たとえば、異なる言語で同じ記事がある場合、実際にはこれらは2つの異なるエンティティであり、コンテンツの団結のサイン。 予想される言語を識別するために、さまざまな方法を使用できます。 最も単純なのは、標準のAccept-Language HTTPヘッダーです。 GETパラメーターlanguage =” en”を追加する、パスプレフィックスexample-api.com/en/を使用する、またはドメインレベルen.example-api.comでさえ、他の方法に出くわしました 。 ロケールを指定する方法の選択は、特定のアプリケーションとそれに直面するタスクに依存するように思えます。
内部ルーティング
そこで、API（またはそのコンポーネントの1つ）のルートノードに到達しました。 それ以降のすべてのルートは、サポートされているリソースのセットに従って、サーバーアプリケーション内に直接移動します。
収集パス
コレクションへのパスを示すために、対応するエンティティの名前を使用します。たとえば、これがユーザーのリストである場合、パスは/ usersになります 。 コレクションには、 GET （エンティティの限定リストを取得）とPOST （新しい要素を作成）の2つのメソッドが適用できます。 リストのリクエストでは、ページネーション、ソート、フィルタリング、検索などに使用される多くの追加のGETパラメーターを使用できますが、これらはオプションである必要があります。 これらのパラメーターはパスの一部として渡さないでください！
コレクション要素
コレクションの特定の要素を参照するには、ルートで一意の識別子/ユーザー/ 25を使用します 。 これはユニークな方法です。 オブジェクトを操作するには、 GET （オブジェクトの取得）、 PUT / PATCH （変更）、およびDELETE （削除）のメソッドが適用可能です。
ユニークなオブジェクト
多くのサービスには、現在のユーザーのプロファイル 、または個人設定/設定など、現在のユーザーに固有のオブジェクトがあります 。 もちろん、一方で、これらはコレクションの1つの要素ですが、Web APIクライアントアプリケーションを使用するための出発点であり、データに対する操作の範囲を大幅に拡大できます。 ただし、ユーザーの設定を保存するコレクションには、データのセキュリティとプライバシーの理由からアクセスできない場合があります。
オブジェクトとコレクションのプロパティ
オブジェクトのプロパティに直接アクセスするには、オブジェクトへのパスにプロパティ名を追加するだけです。たとえば、ユーザー名/ユーザー/ 25 /名前を取得します。 メソッドGET （値の取得）およびPUT / PATCH （値の変更）は、プロパティに適用できます。 DELETEメソッドは適用されません。 プロパティは、データの形式化された単位としてのオブジェクトの構造部分です。
前のパートでは、オブジェクトなどのコレクションが独自のプロパティを持つ方法について説明しました。 私の記憶では、countプロパティだけが必要でしたが、アプリケーションはより複雑で具体的かもしれません。 コレクションのプロパティへのパスは、その要素のプロパティと同じ原則に基づいて構築されます：/ users / count。 コレクションプロパティの場合、 GETメソッド（プロパティの取得）のみが適用されます。 コレクションは、リストにアクセスするための単なるインターフェースです。
関連オブジェクトのコレクション
オブジェクトプロパティの種類の1つは、関連オブジェクトまたは関連オブジェクトのコレクションです。 そのようなエンティティは、原則として、オブジェクトのプロパティではなく、他のエンティティとの関係への参照にすぎません。 たとえば、ユーザー/ users / 25 / rolesに割り当てられたロールのリスト。 ネストされたオブジェクトとコレクションの操作については、次のいずれかの部分で詳しく説明しますが、この段階では、オブジェクトの他のプロパティと同様に、それらに直接アクセスできれば十分です。
オブジェクトとコレクションの機能
コレクションまたはオブジェクトの関数呼び出しインターフェイスへのパスを構築するには、プロパティにアクセスする場合と同じアプローチを使用します。 たとえば、 / users / 25 / sendPasswordReminderオブジェクトまたは/ users / disableOldコレクションの場合 。 関数呼び出しの場合は、とにかくPOSTメソッドを使用します。 なんで？ クラシックRESTには、関数を呼び出すための特別な動詞がないため、既存のRESTのいずれかを使用する必要があることを思い出してください。 私の意見では、POSTメソッドはこれに最も適しています。 これにより、必要な引数をサーバーに渡すことができます。これは多重呼び出し不変ではなく（複数のアクセスで同じ結果を返す）、セマンティクスで最も抽象的です。
すべてが多かれ少なかれシステムに適合していることを願っています:)次のパートでは、リクエストとアンサー、そのフォーマット、ステータスコードについて詳しく説明します。