[WIP] Microsoft REST API Guidelines を読もう

2022-07-15

Microsoft REST API Guidelines を読んで気になったところメモ。

6. Client guidance

クライアントは、未知のフィールドを無視しなければならない。(MUST)

APIのレスポンスに新規フィールドを追加したときに、エラーを起こさないため？

移動したり名前を変更したりできるリソースは、一意の識別子を含むURLも公開するべき。(SHOULD)

このとき、識別子は GUID でなくてもよい。

ユーザーフレンドリーな構造化されたURL :

https://api.contoso.com/v1.0/people/jdoe@contoso.com/inbox

識別子で表現したURL :

https://api.contoso.com/v1.0/people/7011042402/inbox

操作は可能な限り適切なHTTPメソッドを使用しなければならず(MUST)、操作の冪等性は尊重されなければならない。(MUST)

以下のメソッドを使用するすべてのリソースは、その使用方法に準拠しなければならない。

Method	Description	冪等性
GET	オブジェクトの現在の値を返す	True
PUT	オブジェクトを置き換える。該当するオブジェクトが無ければ、作成する	True
DELETE	オブジェクトを削除する	True
POST	オブジェクトを作成する	False
HEAD	GETレスポンスに対して、オブジェクトのメタデータを返す	True
PATCH	オブジェクトの一部をアップデートする	False
OPTIONS	リクエストに関する情報を取得する	True

POST のレスポンスには、作成したデータの情報を返すとよい

ここまで読んだ