[ターン] RESTfulAPIのベストプラクティス

この記事は以下から複製されています：http：//www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html

RESTful は、現在、Webデータインターフェイスの設計で最も人気のあるAPI設計仕様です。

その一般的な原則は理解しやすいですが、詳細を正しく理解するのは簡単ではありません。この記事では、RESTfulの設計の詳細を要約し、理解しやすく使いやすいAPIを設計する方法を紹介します。

1.URLデザイン

1.1動詞+目的語

RESTfulの中心的な考え方は、クライアントによって発行されたデータ操作命令がすべて「動詞+目的語」の構造にあるということです。たとえば、GET /articlesこのコマンドGETは動詞と/articlesオブジェクトです。

動詞は通常、CRUD操作に対応する5つのHTTPメソッドです。

GET：読む

POST：作成

PUT：更新（更新）

パッチ：更新（更新）、通常は部分的な更新

DELETE：删除（Delete）

HTTP仕様によれば、すべての動詞は大文字になります。

1.2動詞の範囲

一部のクライアントはGET、POST両方の方法のみを使用します。サーバは受け入れなければならないPOSTアナログ他の三つの方法をPUT（PATCH、DELETE）。

このとき、クライアントから送信されるHTTPリクエストはX-HTTP-Method-Override、POSTメソッドをオーバーライドするためにどの動詞を使用するかをサーバーに通知する属性を追加する必要があります。


POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

上記のコードでX-HTTP-Method-OverrideはPUT、このリクエストを指定する方法は、ではなくPOSTです。

1.3オブジェクトは名詞でなければなりません

オブジェクトはAPIのURLであり、HTTP動詞のオブジェクトです。動詞ではなく名詞でなければなりません。たとえば、/articlesこのURLは正しいですが、以下のURLは名詞ではないため、すべて間違っています。

/ getAllCars

/ createNewCar

/ deleteAllRedCars

1.4複数のURL

URLは名詞なので、複数形にするべきですか、それとも単数形にするべきですか？

統一されたルールはありませんが、一般的な操作は、GET /articles（すべての記事を読む）などのコレクションを読み取ることです。これは明らかに複数形である必要があります。

一貫性を保つために、GET /articles/2より良いなど、複数のURLを使用することをお勧めしますGET /article/2。

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ステータスコードとデータの2つの部分が含まれます。

HTTPステータスコードは、5つのカテゴリに分類された3桁の数字です。

1xx：関連情報

2xx：正常動作

3xx：リダイレクト

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

5xx：サーバーエラー

これらの5つのカテゴリには、考えられるほとんどの状況をカバーする、合計100を超えるステータスコードが含まれています。各ステータスコードには標準の（または合意された）解釈があります。クライアントはステータスコードを表示するだけで何が起こったかを判断できるため、サーバーはステータスコードをできるだけ正確に返す必要があります。

APIは1xxステータスコードを必要としません。他の4種類のステータスコードの正確な意味を以下に説明します。

2.22xxステータスコード

200ステータスコードは、操作が成功したことを示しますが、メソッドが異なれば、より正確なステータスコードを返すことができます。

GET：200 OK

POST：201作成

置く：200 OK

パッチ：200 OK

削除：204コンテンツなし

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

さらに、202 Acceptedステータスコードは、サーバーがリクエストを受信したが、まだ処理していないことを示し、通常は非同期操作のために、将来的にリクエストを処理します。以下に例を示します。


HTTP/1.1 202 Accepted

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

2.33xxステータスコード

APIは、301ステータスコード（永続的なリダイレクト）と302ステータスコード（一時的なリダイレクト、これ307も意味します）を使用しません。これらはアプリケーションレベルで返される可能性があり、ブラウザが直接ジャンプするためです。APIレベルでは、これらを考慮する必要はありません。 2つのケース。

API3xxで使用されるステータスコードは、主に303 See Other、別のURLを参照します。これ302と307同じような意味、「一時的なリダイレクト、」違いがそれである302、と307のためのGET要求、および303ためPOST、PUTとDELETE要求。それを受け取っ303た後、ブラウザは自動的にジャンプしませんが、ユーザーが次に何をするかを決定することができます。以下に例を示します。


HTTP/1.1 303 See Other
Location: /api/orders/12345

2.44xxステータスコード

4xxステータスコードは、主に次のようにクライアントエラーを示します。

400 Bad Request：サーバーはクライアントの要求を理解せず、処理も行いませんでした。

401 Unauthorized：ユーザーが認証資格情報を提供しなかったか、認証に合格しませんでした。

403 Forbidden：ユーザーは認証に合格しましたが、リソースにアクセスするために必要な権限がありません。

404 Not Found：要求されたリソースが存在しないか、使用できません。

405 Method Not Allowed：ユーザーは認証されていますが、使用されているHTTPメソッドはユーザーの権限の範囲外です。

410 Gone：要求されたリソースはこのアドレスから転送され、使用できなくなりました。

415 Unsupported Media Type：クライアントから要求された戻り形式はサポートされていません。たとえば、APIはJSON形式のみを返すことができますが、クライアントはXML形式を返す必要があります。

422 Unprocessable Entity ：クライアントがアップロードした添付ファイルを処理できないため、リクエストが失敗します。

429 Too Many Requests：クライアントリクエストの数が制限を超えています。

2.55xxステータスコード

5xxステータスコードはサーバーエラーを示します。一般的に、APIはサーバーの詳細情報をユーザーに開示しないため、2つのステータスコードで十分です。

500 Internal Server Error：クライアント要求は有効であり、サーバー処理中に事故が発生しました。

503 Service Unavailable：サーバーはリクエストを処理できません。通常、ウェブサイトのメンテナンスステータスに使用されます。

3、サーバーの応答

3.1純粋なテキストに戻らないでください

APIによって返されるデータ形式は、プレーンテキストではなく、JSONオブジェクトである必要があります。これにより、標準の構造化データを返すことができるためです。したがって、サーバー応答のHTTPヘッダーのContent-Type属性を設定する必要がありますapplication/json。

クライアントがリクエストするときは、JSON形式を受け入れることができることもサーバーに明確に伝える必要があります。つまり、リクエストのHTTPヘッダーのACCEPT属性も設定する必要がありますapplication/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がどのように設計されているかを知らない可能性があります。1つの解決策は、次のステップを容易にするために、応答に関連するリンクを提供することです。この場合、ユーザーは1つのURLを覚えるだけでよく、他のURLを見つけることができます。この方法はHATEOASと呼ばれます。

たとえば、すべての GitHubAPI はドメイン名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を取得できます。ユーザーの場合、URLのデザインを覚えておく必要はありません。api.github.comから段階的に調べてください。

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" }
  ]}
}

4、参照リンク

RESTful APIデザイン：ユーザーを幸せにする13のベストプラクティス、Florimond Manca
MicroSoftAzureによるAPI設計

（終了）