REST Web API サービス設計

参考：Udemy コース

---

WEB API とは

Web サービスで提供している機能やデータを外から利用できるように定義したルールまたは実装のこと。

意訳
ある WEB サービスの機能と使ったりデータを取ったりする際のインターフェイス的なもの。

Restful な URI の設計方法

ルール

1.短くて入力しやすい（覚えやすい）ものにすること

# 悪い例
GET http://api.example.com/service/api/search

# 良い例
GET http://api.example.com/search

2.省略しすぎない（独自の用語、略語を利用しない）

# 悪い例
GET http://api.example.com/us

# 良い例
GET http://api.example.com/user

3.URI は全て小文字で構成する。

# 悪い例
GET http://api.example.com/User

# 良い例
GET http://api.example.com/user

4.単語はハイフンで繋げる（本当はハイフンで繋げるぐらいならパスを分けたほうが良い）。

# 悪い例
GET http://api.example.com/popular_users

# 良い例
GET http://api.example.com/popular_users

# もっと良い例(人気のあるユーザー → ユーザーの中の人気者)
GET http://api.example.com/users/popular

5.単語は複数形で使用する。

# 悪い例
GET http://api.example.com/user

# 良い例
GET http://api.example.com/users

6.エンコードが必要な文字（日本語）を使わない。

# 悪い例
GET http://api.example.com/ユーザー

# 日本語がエンコードされるとパッと見意味不明なURIになる。
GET http://api.example.com/%E3%83%A6%E3・・・・・

7.サーバー側で使用している技術が見えないようにする。

# 悪い例
# 「cgi」「php」を使っていることがバレているのでこれら技術の脆弱性が狙われやすくなる。

GET http://api.example.com/cgi-bin/get_user.php?id=12345

# 良い例
GET http://api.example.com/users/12345

8.変更しやすいものにする。

# 悪い例
# ロードバランサで複数サーバー使用している場合に見分けがつくようにしているのかもしれないが、パッと見では意味がわからないURIになるし、変更の際に個別に対応しなければならなくなる。

GET http://api.example.com/users/serverA/12345

GET http://api.example.com/users/serverB/12345

# 良い例
# 複数サーバー存在してもそれは裏側の話としてURIには反映しない。

GET http://api.example.com/users/12345

9.URI の設計ルールを統一する。（パラメータをクエリで渡すか、パスパラメータとして渡すか）

# 悪い例
# GET時はクエリパラメータで情報を渡しているのに、POST時はパスパラメータとして渡しており統一されていない。

GET http://api.example.com/users?id=12345

POST http://api.example.com/users/12345/message

# 良い例
#
GET http://api.example.com/users/12345

POST http://api.example.com/users/12345/message

パラメータの渡し方について

パラメータの渡し方にはクエリパラメータとパスパラメータの２種類がある。

・クエリパラメータ

# URI末尾の「?」以降、「パラメータ名=値」で渡す。
GET http://api.example.com/users?id=12345

・パスパラメータ

# URIの一部としてパラメータを埋め込む。
GET http://api.example.com/users/12345

・どっちを使うか

パターン	パラメータ
一意なリソースを表す場合	パスパラメータを使用
省略可能（なくても実行できる）場合	クエリパラメータを使用

ステータスコード

処理結果を表すもの。

番号帯	番号	意味
100番台	情報
	100 Continue	サーバーで処理中。拒否はされていない状態。
	101 Switching Protocol	プロトコルの切り替え要求。
200番台	成功
	200 OK	リクエスト成功。本文データ含む。
	200 Created	リクエストが成功し、リソースが作成されたことを表す。ヘッダーのLocationに作成したリソースへのURLを含む。
	200 Accepted	非同期ジョブを受け付けたことを示し。処理結果は別途受け取る。
	200 No Content	リクエストが成功し、クライアント側のビューを変更する必要があるようなレスポンスデータがないことを表す。
300番台	リダイレクト	※RestAPIではリダイレクトを実装しないため省略。
400番台	クライアントサイドのエラー
	400 Bad Request	その他全般のエラー
	401 Unauthorized	未認証エラー
	403 Forbidden	アクセス権のないリソースへのアクセスでエラー　※対象リソースが存在するということがわかってしまうので、画面表示は404として処理することが多い。
	404 Not Found	リクエスト対象リソースが存在しないことを表す。
	409 Conflict	リソースの競合によるエラー
	429 Too Many Request	アクセス回数が制限（レートリミット）を超えたために処理ができなかった場合。
500番台	サーバーサイドのエラー
	500 Internal Server Error	サーバーサイドでアプリケーションエラーが発生した場合
	503 Service Unavailable	メンテナンスなどでアプリケーションが一時的に利用できないことを示す場合。

HTTPメソッドとステータスコード

○GET メソッドが返すステータスコード例

・成功例

No.	メッセージ	概要
200	OK
304	Not Found	キャッシュを利用する場合

・失敗例

No.	メッセージ	概要
400	Bad Request	リクエストに誤りがある場合
401	Unauthorized	認証に失敗した場合
403	Forbidden	認証後にアクセスしようとしたリソースに権限がない場合
404	Not Found	リソースが存在しない場合
429	Too many Request	レートリミット制限を超えた場合
500	Internal Server Error	サーバーサイドの処理でエラーが発生した場合
503	Service Unavailable	高負荷などでサーバーが応答できない場合

○POST メソッドが返すステータスコード例

・成功例

No.	メッセージ	概要
200	OK	レスポンスに登録データを含む場合
201	Created	レスポンスボディーは空で Location に新リソースの URL を返す場合
202	Accepted	非同期処理などでデータを受け渡した場合

・失敗例

※以下に記載のもの以外は GET の場合と同様

No.	メッセージ	概要
409	Conflict	同じデータを複数ユーザーが尊くしようとして衝突した場合

○PUT メソッドが返すステータスコード例

・PUT はデータの更新、登録の両方で使用される。

・成功例

No.	メッセージ	概要
200	OK	レスポンスに登録済みデータを含む
201	Created	レスポンスボディーは空で Location に新リソースの URL を返す場合
204	No Content	データ更新でレスポンスデータなし（画面更新など不要で戻り値がない場合）

・失敗例

※GET の失敗例を参照

No.	メッセージ	概要
400	Bad Request	クライアント側リクエストの不備
404	Not Found	該当データなし
409	Conflict	他のリクエストと競合した場合

○DELETE メソッドが返すステータスコード例

・成功例

No.	メッセージ	概要
200	OK	削除の場合リクエストにデータを格納することは少ないためあまり使用しない
202	Accepted	非同期処理の受付
204	No Content	削除に成功して対照コンテンツがないことを示す。

・失敗練

※GET の失敗例を参照

No.	メッセージ	概要
404	Not Found	403 Forbidden を隠蔽するために使用

最後に

Udemyの学習コース自体はまだ続いていますが、RestAPIに関する内容としては
以上となります。

応用部分については別途進めてからまとめて投稿したいと思います。