この記事は以下から複製されています: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設計
(終了)