13 RESTful API
6767 ワード
RESTfulは現在最も流行しているAPI設計規範であり、Webデータインタフェースの設計REST、すなわちRepresentational State Transferの略であり、このフレーズの翻訳は「表現層状態転化」である.アーキテクチャがRESTの原則に合致する場合は、RESTfulアーキテクチャと呼ばれます.
一、URL設計
この5つのクラスには、100以上のステータスコードが含まれており、ほとんどの場合をカバーしています.各ステータスコードには標準的な(または約束された)解釈があり、クライアントはステータスコードを表示するだけで、何が起こったのかを判断することができるので、サーバはできるだけ正確なステータスコードを返すべきである.
APIは
GET: 200 OK POST: 201 Created PUT: 200 OK PATCH: 200 OK DELETE: 204 No Content
上記のコードでは、
さらに、
APIは、アプリケーション・レベルから戻ることができ、ブラウザが直接ジャンプするため、APIレベルはこの2つの状況を考慮しなくてもよいため、
APIで使用される
三、サーバー応答
一、URL設計
1.1動詞+目的語
RESTfulの核心思想は,クライアントが発行するデータ操作命令がすべて「動詞+目的語」の構造であることである.例えば、GET/articlesというコマンドは、GETは動詞、/articlesは目的語です.
動詞は通常5種類のHTTPメソッドであり,CRUD操作に対応する.
GET:Read(Read)POST:新規(Create)PUT:Update(Update)PATCH:Update(Update)、通常は部分更新DELETE:削除(Delete)HTTP仕様に従い、動詞はすべて大文字である.
1.2動詞の上書き
一部のクライアントでは、GETとPOSTの2つの方法しか使用できません.サーバは、POSTシミュレーションの他の3つの方法(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が今回のリクエストを指定する方法は、POSTではなくPUTです.
1.3目的語は名詞でなければならない
目的語はAPIのURLであり,HTTP動詞の役割の対象である.それは名詞であるべきで,動詞ではない.例えば、/articlesというURLが正しいのですが、下のURLは名詞ではないので間違いです.
/getAllCars/createNewCar/deleteAllRedCars
1.4複数URL
URLが名詞である以上、複数を使うべきか、単数を使うべきか.
これには統一的な規定はありませんが、一般的な操作はGET/articles(すべての文章を読む)のような集合を読み取ることです.ここでは明らかに複数です.
統一のため、GET/articles/2よりもGET/article/2のような複数のURLを使用することをお勧めします.
1.5マルチレベルURLの回避
一般的に、リソースにはマルチレベルの分類が必要なため、ある著者の文章を取得するなど、マルチレベルのURLを簡単に書くことができます.GET/authors/12/categories/2というURLは拡張に不利で、意味も明確ではなく、意味を理解するにはしばらく考えなければならないことが多い.より良い方法は、第1レベルを除いて、他のレベルはクエリー文字列で表現されます.
GET/authors/12?categories=2次は別の例で、パブリッシュされた記事をクエリーします.次のURLにデザインされるかもしれません.GET/articles/publishedクエリ文字列の書き方は明らかに良いです.GET/articles?published=true
二、状態コード
2.1ステータスコードは正確でなければならない
クライアントのリクエストごとに、サーバが応答する必要があります.応答はHTTPステータスコードとデータの2つの部分を含む.
HTTPステータスコードは3桁で、5つのカテゴリに分かれています.
2.1ステータスコードは正確でなければならない
クライアントのリクエストごとに、サーバが応答する必要があります.応答はHTTPステータスコードとデータの2つの部分を含む.
HTTPステータスコードは3桁で、5つのカテゴリに分かれています.
1xx
:関連情報2xx
:操作成功3xx
:リダイレクト4xx
:クライアントエラー5xx
:サーバエラーAPIは
1xx
ステータスコードを必要とせず、以下に他の4種類のステータスコードの正確な意味を説明する.2.2 xxステータスコード
200
ステータスコードは、動作が成功したことを示すが、異なる方法でより正確なステータスコードを返すことができる.上記のコードでは、
POST
は201
のステータスコードを返し、新しいリソースが生成されたことを示す.DELETE
は、204
ステータスコードを返し、リソースが存在しないことを示す.さらに、
202 Accepted
ステータスコードは、サーバが要求を受信したが、まだ処理されていないことを示し、将来的に再処理され、通常は非同期動作に使用される.次に例を示します.
HTTP/1.1 202 Accepted
{
"task": {
"href": "/api/company/job-management/jobs/2130040",
"id": "2130040"
}
}
2.3 3 xx状態コード
APIは、アプリケーション・レベルから戻ることができ、ブラウザが直接ジャンプするため、APIレベルはこの2つの状況を考慮しなくてもよいため、
301
ステータス・コード(永続リダイレクト)と302
ステータス・コード(一時リダイレクト、307
もこの意味)を使用しません.APIで使用される
3xx
ステータスコードは、主に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.4 4 xxステータスコード
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.5 5 xxステータスコード
5xx
ステータスコードは、サービス側エラーを示す.一般に,APIはサーバの詳細をユーザに漏らすことはないので,2つのステータスコードだけで十分である.500 Internal Server Error
:クライアント要求が有効で、サーバ処理中に予期せぬ事故が発生しました.503 Service Unavailable
:サーバは要求を処理できず、一般的にウェブサイトのメンテナンスステータスに使用されます.三、サーバー応答
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と呼ぶ.
例えば、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から、URL設計を覚える必要はない.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" }
]}
}
GET /orders/2 HTTP/1.1
Accept: application/json
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."
}
}
{
...
"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",
...
}
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" }
]}
}