RESTfulは現在最も流行しているAPI設計規範であり、Webデータインタフェースの設計REST、すなわちRepresentational State Transferの略であり、このフレーズの翻訳は「表現層状態転化」である.アーキテクチャがRESTの原則に合致する場合は、RESTfulアーキテクチャと呼ばれます.

一、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つのカテゴリに分かれています.

1xx:関連情報

2xx:操作成功

3xx:リダイレクト

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

5xx:サーバエラー

この5つのクラスには、100以上のステータスコードが含まれており、ほとんどの場合をカバーしています.各ステータスコードには標準的な(または約束された)解釈があり、クライアントはステータスコードを表示するだけで、何が起こったのかを判断することができるので、サーバはできるだけ正確なステータスコードを返すべきである.
APIは1xxステータスコードを必要とせず、以下に他の4種類のステータスコードの正確な意味を説明する.

2.2 xxステータスコード

200ステータスコードは、動作が成功したことを示すが、異なる方法でより正確なステータスコードを返すことができる.

GET: 200 OK

POST: 201 Created

PUT: 200 OK

PATCH: 200 OK

DELETE: 204 No Content

上記のコードでは、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" }
  ]}
}