REST Web API サービス設計

## 参考：Udemy コース

https://www.udemy.com/course/rest-webapi-development/

---

### 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に関する内容としては
以上となります。

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