RESTfulなインターフェース設計仕様

1.ドメイン名

APIは、専用のドメイン名の下に展開されるようにしてください。

https://api.example.com

それは決定APIは非常に簡単ですされている場合は、それ以上の延長は行われませんメインのドメイン名の下に置かれたと考えることができます。

https://example.org/api/

2.バージョン（バージョン）

APIのバージョン番号は、URLに配置する必要があります。

http://www.example.com/app/1.0/foo

http://www.example.com/app/1.1/foo

http://www.example.com/app/2.0/foo

別のアプローチではなく、便利で直感的なURLへとして、HTTPヘッダ情報内のバージョン番号です。Githubのこの練習の使用に関する。

異なるバージョンなので、同じリソースのようにさまざまな症状を理解することができるので、我々は同じURLを使用する必要があります。バージョン番号は、（参照HTTP要求のAcceptヘッダーフィールドに区別することができるバージョニングRESTサービス）。

Accept: vnd.example-com.foo+json; version=1.0

Accept: vnd.example-com.foo+json; version=1.1

Accept: vnd.example-com.foo+json; version=2.0

3.パス（エンドポイント）

また、「終了」（エンドポイント）として知られている経路は、特定のURLのAPIを表し、各URLは、リソース（資源）を表します

（1）URLなどのリソースは、唯一の名詞は、動詞が持つことはできませんが、この用語は、多くの場合、データベーステーブルの名前に対応して使用されています。

たとえば、次は良い例です。

/getProducts
/listOrders
/retreiveClientByOrder?orderId=1

シンプルな構造のために、あなたは常に用語を使用する必要があります。また、この方法は、分離HTTP URLリソース名を使用して動作させることができます。

GET /products ：将返回所有产品清单
POST /products ：将产品新建到集合
GET /products/4 ：将获取产品 4
PATCH（或）PUT /products/4 ：将更新产品 4

（2）APIは、複数名詞で使用されるべきです。子リソースまたはすべてのリソースかどうか。

例えば、製品を取得するAPIを定義することができます

获取单个产品：http://127.0.0.1:8080/AppName/rest/products/1
获取所有产品: http://127.0.0.1:8080/AppName/rest/products

3. HTTP動詞

操作の特定のリソースタイプに対して、HTTP動詞で表されます。

一般的なHTTP動詞は、（括弧に対応するSQLコマンドである）以下の4つがあります。

GET（SELECT）：サーバー（1以上）からリソースを削除します。
POST（CREATE）：サーバ上に新しいリソース。
PUT（UPDATE）：サーバーに（クライアントが提供する完全なリソースを変更した後）リソースを更新します。
DELETE（削除）：サーバーからリソースを削除します。

3つのあまり一般的でHTTP動詞があります。

PATCH（UPDATE）：（クライアントのプロパティの変更を提供）サーバアップデート（更新）リソース。
HEAD：メタデータのリソースを取得します。
OPTIONS：情報へのアクセス、クライアントのリソースのプロパティを変更することができます。

ここではいくつかの例があります。

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园（上传文件）
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

4.情報のフィルタリング（フィルタリング）

多数のレコード場合は、サーバーはすべて彼らがユーザに返されることはできません。パラメータを提供しなければならないAPIは、フィルタリングの結果が返されます。

ここではいくつかの共通のパラメータがあります。名前= XX＆SSS = XXX：クエリ文字列とそれに続くカラムアドレス疑問符のデータの後に、フォーマットをQUERY_STRING

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

冗長性は、設計パラメータは、すなわち、パラメータがAPIとURLパス時折、重複を許可することができます。例えば、/動物/動物園/ ID /動物をGETとGET？Zoo_id = IDは同じ意味です。

6.ステータスコード（ステータス・コード）

ユーザコードとステータスメッセージにサーバ戻って、共通の数は以下の通りである（括弧内は動詞に対応するHTTPステータスコードです）。

200 OK - [GET]：サーバーが正常にユーザーによって要求されたデータを返します。

201 CREATED - [POST / PUT / PATCH]：正常に新規または変更されたユーザデータ。

受け入れ202 - [*]を示し、要求はバックグラウンド（非同期タスク）にキューイングされています

204 NO CONTENT - [削除]：正常にユーザデータを削除します。

400 INVALID REQUEST - [POST / PUT / PATCH]：ユーザー誤って発行された要求、サーバが動作しない、新規または変更されたデータ

401権限 - [*]：ユーザーが権限（トークン、ユーザ名、パスワードエラー）を持っていないことを示しています。

403禁止 - [*]ユーザが許可されていることを示す（401相対誤差）が、アクセスが禁止されます。

404が見つかりません - [*]：ユーザーがサーバーが操作されていない、記録の要求が存在しない発行し、操作が冪等です。

406許容できない - [GET]：ユーザによって要求されたフォーマットが利用可能でない（例えば、ユーザによって要求されたJSON形式のみXML形式など）。

410ゴーン - [GET]：ユーザの要求リソースは永続的に除去され、そして得られないであろう。

422 Unprocesableエンティティ - [POST / PUT / PATCH]オブジェクトが作成されると、検証エラーが発生します。

500内部サーバーエラー - [*]：サーバーエラーが発生し、利用者は、要求が正常に送信されたかどうかを確認することができません。

ステータスコードの完全なリストは、参照、ここやここ。

取り扱い7.エラー（エラー処理）

ステータスコード4xxの場合、サーバは、ユーザにエラーメッセージを返す必要があります。一般的には、エラー情報がエラーメッセージにキーとしてキー名として返されます。

{
    error: "Invalid API key"
}

8.戻る結果

別の操作については、サーバーにユーザーから返された結果は、以下の仕様を満たす必要があります。

/コレクションをGET：リソースオブジェクトのリスト（配列）を返します。
/コレクション/ IDをGET：単一のリソースオブジェクトを返します（JSON）
POST /コレクション：新しく作成されたリソースオブジェクト（JSON）を返します。
PUT /コレクション/ ID：フルリソースオブジェクトに戻る（JSON）
/コレクション/ IDを削除します。空のドキュメント（空の文字列）を返します

9.ハイパーメディア（ハイパーメディアAPI）

RESTfulなAPIは、ユーザーが文書をチェックするだけでなく、次に何をすべきか分かっていないように、ハイパーメディアを（つまり、返された結果でも、他のAPIメソッドに、リンクを提供）を行うのがベストです。

例えば、GitHubのAPIのは、この設計で、訪問api.github.comは、すべての利用可能なAPIのURLのリストを取得します。

{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}

あなたが訪問に行く必要があり、現在のユーザーの情報を取得したい場合は、上から見ることができapi.github.com/userをして、私は次のような結果を得ることができます。

{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}

上記のコードは、サーバーが迅速な情報、および文書のURLを与えることを示しています。

10.その他

サーバはデータ形式を返し、あなたはXMLの使用を避ける、JSONを使用するようにしてください。