どのようにエレガントなデザインのRESTful API？これは私が話して記事を見てきた最も明確です！

RESTfulなAPIは、Webデータ・インタフェースの設計のための最も人気のある設計仕様です。それは原則を把握するのは簡単ですが、詳細は右行うことは容易ではありません。

この記事では、RESTfulな、そしてどのように理解し、使いやすいAPIを設計する設計の詳細をまとめたもの。

、URLデザイン

1.1動詞+オブジェクト

RESTfulな核となるアイデアは、クライアントデータ操作命令が「動詞+オブジェクト」構造を発行していることです。

例えば、/記事には、このコマンドをGET、GET動詞である、/記事が対象です。HTTP動詞の方法は、通常、CRUD操作に対応する5種類です。

GET：読み取り（リード）

POST：新しい（作成）

PUT：更新（アップデート）

PATCH：通常の更新（アップデート）、部分更新

DELETE：删除（Delete）

HTTPの仕様によると、動詞は資産計上されます。

1.2動詞カバー

一部のクライアントはこれら2つの方法は、GETやPOST、サーバは（、PUT、DELETE PATCH）他の3つのメソッドをシミュレートPOSTを受け入れる必要があります使用することができます

このとき、クライアントからのHTTP要求は、サーバーがPOSTメソッドをカバーし、動詞を使用する必要があります伝えX-HTTP-方法-override属性を追加します。

POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT
复制代码

上記のコードは、X-HTTP-メソッドオーバーライドは、この要求は、方法は、代わりにポストの、置かれる指定します。

1.3オブジェクトは、名詞である必要があります

オブジェクトは、HTTP動詞のアクションの対象となる、URLのAPIです。これは、名詞、動詞ではないはずです。

例えば、/記事このURLは正しいですが、以下のURLは名詞ではない、それは間違っています。

/ getAllCars

/ createNewCar

/ deleteAllRedCars

1.4複雑なURL

URLは名詞であるので、あなたは、複数または単数を使用する必要がありますか？これには、均一な要件ではありませんが、一般的な操作は、コレクションを読み取ることです。

このようなGET /記事（全ての記事を読む）として、これは明らかに複雑でなければなりません。

GET /記事/ 2/2よりも良く、このような記事/ GETとして一貫性のため、提案された使用の複雑なURLについて。

1.5マルチレベルのURLを避けます

一般的な状況では、そのようないくつかの記事の著者へのアクセスとして、マルチレベルのURLを記述するのは簡単ですので、リソースは、マルチレベルの分類に必要があるということです。

GET /authors/12/categories/2复制代码

このURLはセマンティクスが意味を理解するためには、多くの場合、しばらくために、明確ではないが、拡大に資するものです。

いっそ、最初のレベルに加えて、他のレベルは、クエリ文字列表現を使用しています。

GET /authors/12?categories=2复制代码

ここに掲載された記事を照会、別の例です。あなたは、次のURLに設計することができます。

GET /articles/published复制代码

クエリ文字列の文言有意に良好。

GET /articles?published=true
复制代码

第二に、ステータスコード

2.1ステータスコードは正確でなければなりません

各要求のカスタマー終わり、サーバーは応答を与えられなければなりません。レスポンスのHTTPステータスコードは二つの部分とデータを備えます。

HTTPステータスコードは、5つのカテゴリーに分け、3桁の数です。

1xx：関連情報

2xx：操作成功

3xx：リダイレクト

4xx：クライアントエラー

5xx：サーバーエラー

これは、発生する可能性のある状況の大半をカバーし、ステータスコードの100種類の5つのカテゴリーの合計が含まれています。

各ステータスコードは、クライアントが単にあなたが何が起こったのかを判断することができ、ステータスコードをチェックし、そのサーバはできるだけ正確にステータスコードを返すことを標準（または合意）について説明しています。

1xxステータスコードを必要としないAPIは、以下のステータスコードの他の4つの正確な意味を説明しています。

2.2の2xxステータスコード

200ステータスコード、動作を示しているが、別の方法は、より正確にステータス・コードを戻すことができます。

GET：200 OK

POST：201作成されました

PUT：200 OK

PATCH：200 OK

DELETE：204コンテンツなしを

上記のコードでは、POSTは、返し201新しいリソースが生成されることを示すステータスコードと、DELETEは、返し204のリソースが存在しないことを示すステータスコード。

さらに、202受け付けステータスコードは、サーバが要求を受信したことを示しているが、まだ処理されていない、処理が正常に非同期動作のために使用される、将来的にさらにあろう。

ここでは一例です。

HTTP/1.1 202 Accepted

{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}
复制代码

2.3 3xxのステータスコード

API未満301ステータスコード（永久リダイレクト）302および状態（一時的なリダイレクト、307も意味します）

彼らは、アプリケーションレベルで返すことができるので、ブラウザは、APIレベルは、これらの2つの場合を考慮することはできません、直接ジャンプします。

主に303を参照してくださいその他の使用3xxのステータスコードのAPI、別のURLへ急行参照。

それは302と307と同じである意味、ことを除いて、「一時的なリダイレクト」されているPOSTのためのGETリクエスト302と307、および303のために、PUTとDELETE要求。

303を受け取った後、ブラウザが自動的にジャンプし、ユーザーが次に何をするかを決めることはできません。

ここでは一例です。

HTTP/1.1 303 See Other
Location: /api/orders/12345复制代码

2.4 4xxのステータスコード

4xxのステータスコードは、クライアントのエラーを示し、次のカテゴリは次のとおりです。

バート・400の要求：サーバーは、任意の治療を行うことなく、クライアントの要求を理解していません
不正な401：ユーザーが認証資格情報を提供していない、または認証されていません
403禁断のユーザーが認証されていますが、アクセスリソースに必要な権限を持っていません。
見つかりませんでした404：要求されたリソースが存在しない、または利用できないん
方法、不可405：ユーザが認証されていますが、使用されるHTTPメソッドが彼の範囲内ではありません
410ゴーン：このアドレス転送から要求されたリソースが使用できなくなりました
サポートされていないメディアタイプ415：クライアントは、戻りフォーマットがサポートされていません要求されました。例えば、APIはJSON形式を返しますが、クライアントはXML形式を返すように要求されました
処理不能エンティティ422：クライアントのアップロード添付ファイルが失敗した要求で、その結果、処理できません。
あまりにも多くのリクエスト429：クライアント要求の数が制限を超えています。

2.5 5xxのステータスコード

5xxのステータスコードは、サーバーのエラーことを示しています。一般的には、APIサーバーの詳細は限り2つのステータスコードが十分であるとして、利用者に開示することはありません。

500内部サーバーエラークライアント要求は、サーバープロセスの有効なときに事故が発生しました：
503とサービス利用不可ペーパー：サーバーは要求を処理できませんでした、一般的にサイトのメンテナンスの状態で使用

第三に、サーバーが応答します

3.1純粋な紙には戻りません。

それは構造化データの標準に戻すことができるので、APIが返すデータの形式は、プレーンテキストではなく、JSONオブジェクトではありません。

そのため、サーバーはContent-TypeのHTTPヘッダー属性がアプリケーション/ JSONに設定されていると応答します。

ときにクライアント要求JSON形式を受け入れることができ、それは明らかにサーバーに指示する必要があり、HTTPヘッダーを要求されたACCEPT属性は、アプリケーション/ JSONに設定する必要があります。

ここでは一例です。

GET /orders/2 HTTP/1.1 
Accept: application/json
复制代码

3.2エラーが発生した場合、200のステータスコードを返しません。

一つのアプローチは、次のようなステータスコード200、エラー情報が、データの本体の内部に配置され、返し、エラーが発生しても、不適切です。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}
复制代码

上記のコードでは、データ本体を解析した後に、動作を知るために失敗しました。

このような行為は完全に望ましくない事実キャンセルステータスコード、です。正しいアプローチは、あるステータスコードエラーが発生した反映するように、データにエラー特定情報は体内返されます。

ここでは一例です。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}
复制代码

3.3リンク

ユーザーが知らないかもしれないAPIは、URLがどのようなデザインです。一つの解決策は、応答して、次のステップを容易にするためのリンクを与えられていることです。

この場合、ユーザーはちょうどあなたが他のURLを見つけることができ、URLを覚えています。このメソッドは、HATEOASと呼ばれています。

例えば、GitHubでのAPIは、このドメインapi.github.comです。それにアクセスするには、他のURLを取得することができます。

{
  ...
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  ...
}复制代码

上記に対応して、URLへのアクセスを選んで、あなたは別のURLを取得することができます。ユーザーのために、デザインは単にapi.github.comからのステップバイステップを見て、URLを覚えておく必要はありません。

HATEOAS形式は、上記の例のための仕様ではありません、GitHubには、他の属性と一緒にそれらを置きます。より良い方法は、他の属性とのリンクを分離することです。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "In progress",
   "links": {[
    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
    { "rel":"edit", "method": "put", "href":"/api/status/12345" }
  ]}
}复制代码

終わり

著者：ルアンYifeng

出典：

http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html

この記事では、すべての作者に属します

ロングプレスマップ2次元コード、ジャコウネコの即時懸念[技術]巣

アリ、Jingdongは、米国のグループは、バイトに基づいて上位技術専門家を打ちます

ITの人々は、「温度」技術の巣を作成します！