【🔰初心者】【API】RESTfulなAPIのリクエストとレスポンスについて
最近APIの設計について考えることが多かったのでまとめておきます。
※RESTFulとは何か、については言及しません。
あくまでリクエストとレスポンスの設計について言及します。
そもそもAPIとは
まず自分が初心者である時一番わからなかったのがAPIって何ってことでした。
偏見イメージで話すと、アプリケーションとアプリケーションを繋げるアダプタのようなものです。
皆さん例えばパソコンとモニターをつなぐケーブルをお持ちですか？
自分のパソコンが出力できる形と、モニターへ入力できる形って違っていますよね？
それを整形して、繋げてあげるのがケーブル、つまりAPIの役割です。
サーバ側：APIから受け取ったリクエストからデータをAPIに返す
API：特定のリクエストを受け取ってサーバ側に渡す
サーバで処理した後のデータをJSON形式で返す
フロント側：JSONしか受け取らない、APIから帰ってきたデータを整形して表示する
イメージとしてはこんな感じです。
なので、APIを考えるときは、
「どんなリクエストに対して、どんなレスポンスを返す必要があるのか」
を考えます。
多分あんまりわからないと思うので、もう少し具体的に考えてみます。
この記事にめちゃくちゃお世話になりました。ありがとうございます。土下座
例えばよくある、usersというリソースのCRUD処理について考えます。
/users(単数形)についてRESTfulなAPIを考える
まずは、単純な単数形で考えます。あくまで一例です。
レスポンスなどは特にベストプラクティスではありませんのでご注意ください。
▼CREATE
Request：POST /users
Response：201 CREATEしたuserリソース
ユーザは基本的に、createしたあとは自分の入力データがちゃんと保存されたかどうか？
という答えを求めるます。なので、成功レスポンスにはリソースを含める必要がありますね。
▼READ
Request：GET /users/{userId}
Response：200 要求したリソース(指定idのuserリソース)
ユーザは指定IDのuserを要求しており、今回は要求されたリソースを返します。
▼UPDATE
Request：PUT /users/{userId}
Response：201 UPDATEしたuserリソース
CREATEと同様、ユーザは自分の入力データがちゃんと更新できたかどうか？
を求めています。なので、成功レスポンスにリソースを含めます。
▼DELETE
Request：DELETE /users/{userId}
Response：204 NoContent
削除したあと、自分がどんなデータを削除したか気にしたことがあるでしょうか？
ユーザは削除に成功したかどうかは求めますが、
DELETEは中身を必要としないケースが多いです。
今回も同様のため、204でリソースを含んでいません。
こんな感じです。
ただ、複数形になるとそれはそれで変わります。(これも一例)
/users(複数形)についてRESTfulなAPIを考える
単数と複数で、何が変わりますか？
リクエストもしかり、(例えば一括削除なんかはどうでしょうか？)
レスポンスもしかりですね。
なぜなら、100件をCREATEした時に、100件がCREATEされたかどうかをきにする人はいたとしても、
100件のリソース全てをチェックしたいと思うユーザはどれほどいるでしょうか？
それを踏まえて、同様にAPIを考えてみます。
▼CREATE
Request：POST /users/create
Response：204 No Content
上に書いた内容と同様で、100件など多くの一括操作は中身を求めません。
▼READ
Request：GET /users
Response：200 要求したリソース(user一覧のリソース)
user一覧を要求し、それに対してuser一覧を返します。
▼UPDATE
Request：POST /users/update
Response：204 No Content
CREATEと同様ですね
POSTリクエストのbodyに、どのデータをどうupdateするのか
を含めます。
▼DELETE
Request：POST /users/delete
Response：204 NoContent
POSTリクエストのbodyに、どのデータをdeleteするのか
を含めます。
参考URL
http://www.atmarkit.co.jp/ait/articles/1511/19/news022_3.html
https://developer.cybozu.io/hc/ja/categories/200147600-kintone-API
https://developer.github.com/v3/
http://doc.ec-cube.net/api_policy
以上
APIについては色々意見があると思いますが
ざっくり今日考えたのはこんな感じ。
ではまた！
