API設計まとめ

## この記事について
はじめてWeb API設計を担当し、設計することを通して学んだAPI設計のベストプラクティスやHTTPやRESTについて整理したいと考えこの記事を書きました。
応用的な内容よりかなり基本的な内容中心となっております。

## RESTとは
`Representational State Transfer`の略。
`REST`とはWebのアーキテクチャスタイル、または設計思想のことをさす。（つまりはシステムのアーキテクチャを決定する際の羅針盤のような存在）
`REST`の特徴は以下の6つ。

* クライアント/サーバ
* ステートレスサーバ
* キャッシュ
* 統一インターフェース
* 階層化システム
* コードオンデマンド

上記の特徴にしたがっていることを`RESTful`といい、`REST`の原則に基づいて設計されているAPIを`RESTful API`と呼ぶ。

### クライアント/サーバー
クライアントとサーバーを分離し、それぞれを個別に進化させるという考え。
クライアントはユーザーインターフェースを担当し、サーバーはデータ処理や保存を担当することでクライアント側はマルチプラットフォーム化できるほか、サーバーは冗長化し可用性を高めることができる。
このことからお互いに影響を受けずに独立して更新・拡張をすることができる。

### ステートレスサーバ
クライアントのアプリケーション状態をサーバー側で管理しないことを意味する。
サーバーはクライアントからのリクエストのみに依存する。
このためクライアントからの処理を終えるとサーバーはすぐに計算リソースを解放することができる。

### キャッシュ
一度取得したリソースをクライアント側で保存して使い回すこと。
サーバーとクライアント間の通信を減らしてより効率的に処理ができるようにするための仕組み。
ただし、場合によっては古い情報が返ってしまうため注意する。

### 統一インターフェース
リソースに対する操作を統一されたインターフェースで行う。
URIでリソースを指定し、リソースへの操作を8つのHTTPメソッドで定義することによってシンプルで直感的な操作となる。

### 階層化システム
クライアントとサーバーの間にロードバランサーやプロキシなどを設置していくつかの階層に分離するアーキテクチャスタイル。
インターフェースが統一されているため接続先がサーバーであろうがプロキシであってもクライアントは意識する必要がなくなる。

### コードオンデマンド
RESTの6つの特徴のうち唯一のオプショナルな特徴。
コードをサーバーからダウンロードし、クライアント側で実行するアーキテクチャスタイルを指す。

## HTTPメソッド
クライアントはHTTPリクエストをサーバーに送信し、処理をサーバーに依頼する。
HTTPリクエストは
* リクエストライン
* リクエストヘッダ
* リクエストボディ

の構成となっていて、リクエストライン内のHTTPメソッドを使用してクライアントが行いたい処理をサーバーに伝えている。（つまりクライアントがどうしたいかをHTTPメソッドを通してサーバーに伝えている。）
RESTful APIで使用頻度が高いメソッドは`GET`、`POST`、`PATCH`、`DELETE`の4つ。

### GET
URIで指定されたリソースを取得するHTTPメソッド。
HTTPメソッドの中で一番使われる。

### POST
新しい情報を登録するために利用する。（情報を更新するメソッドではない。）
情報を新規登録する場合にはPOSTが適当だが、削除するときにはPUTやDELETEを使うべき

### PUT
既存リソースを完全に上書きするメソッド。
URIで指定されたリソースがない場合には新しいリソースを作成することも可能だが、新しいリソースを作成するときにはPOSTを利用するべき。
POSTの場合はリソースが存在しない場合にURIの決定権はサーバーにあり自動的にURIが割り当てられるが、PUTの場合にはURIの決定権はクライアントにありクライアントとサーバーの結合が密になるためPUTはリソースの更新のみに使うべき。

### PATCH
PUTと異なり全てを変更するのではなく、一部を変更するメソッド。

### DELETE
URIで指定されたリソースを削除するメソッド。

## ステータスコード
ステータスコードはレスポンスメッセージを意味するもの。
正しくステータスコードを使わないとクライアントを混乱させるため、仕様に定められた正しいステータスコードを使う。
ステータスコードは３桁の数字で表され、先頭の数字で5つに分類される。

|ステータスコード|内容|
|---|---|
|100番台|処理中|
|200番台|成功|
|300番台|リダイレクト|
|400番台|クライアントエラー|
|500番台|サーバーエラー|

https://developer.mozilla.org/ja/docs/Web/HTTP/Status

### 200 OK
リクエストが成功したことを示す。
リクエストのHTTPメソッドによって成功が表すことは異なる。
`GET`の場合にはレスポンスボディに読み込まれたリソースが入り、`PUT`や`POST`の場合には処理の結果がボディに入る。

### 201 Created
リクエストが成功し、その結果新しいリソースが作成されたことを示す。`POST`や`PUT`のレスポンスとして返る。
`POST`の場合、新しく作成したリソースのURIがLocationヘッダで返される。

### 400 Bad Request
リクエストの構文やパラメータが間違っているためサーバーがリクエストを理解できないことを示す。

### 401 Unauthorized
クライアントがリクエストを行うためには認証されている必要があることを示す。

### 403 Forbidden
クライアントは認証されているが、クライアントがリクエストをする権限がないことを示す。

### 404 Not found
URIで指定されたリソースがサーバー上に存在しないことを示す。

### 503 Service Unavailable
サーバーが何かしらの原因（過負荷やサーバーダウン）でクライアントからのリクエストを受け付けることができない状況。

## エンドポイント設計

### 短く入力しやすい
無駄な情報を省いてわかりやすいAPIにする。
【BAD】 
```
https://api.example.com/services/api/products
```
【GOOD】 
```
https://api.example.com/products
```

### 人間が読んで理解できるURI
短くするあまり極端に略しすぎない。
【BAD】 
```
https://api.example.com/p
```
【GOOD】 
```
https://api.example.com/products
```

### 大文字小文字が混在していない
基本的に小文字を使用する。
【BAD】 
```
https://api.example.com/Products
```
【GOOD】 
```
https://api.example.com/products
```
### 英単語の誤用には気をつける
意味としては同じだが微妙にニュアンスが異なる英単語には気をつける。
例えば飲食店の予約管理をするAPIを設計する際に「予約」の意味となる単語は`reservation`と`appointment`のふたつがあるが、`reservation`は`場所に対しての予約`、`appointment`は`人に対しての予約`という意味の違いがある。そのためこの場合であれば`resevation`がふさわしい単語になる。

### スペースやエンコードを必要する文字は使わない
URIには利用できない文字があり、そういった文字は[パーセントエンコーディング](https://developer.mozilla.org/ja/docs/Glossary/Percent-encoding)されるため、とても見にくいURIとなるので使わない。
※パーセントエンコーディングとはURIに使えない文字列を半角英数字の組み合わせに置き換えること。
また、ホワイトスペースは`+`で変換される。パーセントエンコーディングほど読みにくくはないが美しくないので使うのは避ける。

### 単語を繋げる必要がある場合にはハイフンを使用する
特別決められたルールはないが
* URI中のホスト名はハイフンを許可されているがアンダースコアは使えない
* ドットは特別な意味を持つ

ということからURI全体でルールを保つためにもハイフンで単語を繋ぐのがベター。
※ただ複数の単語を繋ぎ合わせることは極力避ける。使う必要が出てきた場合にはまず設計を見直して回避できないか考える。

### 一意なリソースを表す場合はパスを使う
例えば商品を取得するAPIで、商品idを指定することで一意の商品が決まるためパスの中に入れるのが良い。
```
https://api.example.com/products/1
```

### 省略可能であればクエリパラメータを使う
sortやlimitのように特定のものに条件を付け加えて、条件がなければデフォルトのものが適用されるケースにはクエリパラメータを使う。
```
https://api.example.com/products?sort=true?limit=10
```

### 名詞の複数形を使用する
APIはリソースを表すもののため、URIには**名詞**を使用する。
またリソースの集合体のため**複数形**とする。

## レスポンスデータ設計

### エンベロープを使わない
以下の理由からエンベロープは使うべきではない。
* HTTPがエンベロープの役割を果たしている
* 1.からエンベロープを使っているレスポンスは冗長


すべてのAPIが同じAPIの共通構造を返すために実際のレスポンデータをラップしていることをエンベロープという。以下の例で言えば`header`や`result`がエンベロープにあたる。
``` JSON
{
    "header": {
        "code": "0",
        "message": "success"
    },
    "result": {
        "vegetables": [
            {
                "id": 1,
                "name": "にんじん",
                "price": 100
            },
            {
                "id": 2,
                "name": "たまねぎ",
                "price": 150
            }
        ]
    }
}
```
Web APIはHTTPを利用していて、HTTPヘッダーやレスポンスボディがエンベロープで使われている`header`や`result`の役割を果たしている。また後述するがレスポンスヘッダでは`200`を返すが、レスポンスボディ内で`404`を返した場合にはクライアント側でエラーが起きていることを認知できない可能性があるためレスポンスヘッダで正しいステータスコードを返す。

### エラーはステータスコードで返す
クライアントのライブラリではレスポンスのステータスコードを使ってエラー分岐をしている場合があり、正しいステータスコードを返さないとエラー処理が行えない可能性がある。
そのためリクエストが成功した場合には`200番台`、クライアント側に問題がある場合には`400番台`、　サーバー側に問題がある場合には`500番台`のステータスコードを返す。
また、クライアントからのリクエストに成功した時のみ`200番台`のステータスコードを返してはならない。

### レスポンスボディでエラーの詳細を返す
ステータスコードは汎用的かつ一般的なものなのでエラーの詳細まではわからず不十分である。
そのためレスポンスヘッダやレスポンスボディでエラーの詳細をクライアントに返す。

### データの構造はできる限りフラットにする
ネストするとJSONのデータサイズが大きくなってしまうため不要なネストは避ける。
ただし、ネストした方がわかりやすい場合にはネストも取り入れる。

### fieldsパラメータなどを使う
APIを叩く回数を減らすためにたくさんのデータを返すことで解決ができるが、大量のデータをクライアントが受け取らなければならなくなりクライアントへの負担が増える。
そのためできる限りレスポンスデータを抑えるために`fields`パラメータなどを使ってクライアントがレスポンスデータを選択できる仕組みを作る。

## 感想
API設計を始めるのであればWeb API The Good Partsを読むべきと先輩エンジニアから勧めてもらいましたがその通りでした。
またHTTPの仕組みを最大限活用しながらAPIを設計することが大切だとも感じたのでWebを支える技術も参考にしながら設計するのがとても良いと感じました。

## 参考
[Webを支える技術](https://gihyo.jp/book/2010/978-4-7741-4204-3)
[Web API The Good Parts]()
[API設計スキルを次のレベルに引き上げるベストプラクティス22選](https://qiita.com/baby-degu/items/6f516189445d98ddbb7d)
[API設計まとめ](https://qiita.com/KNR109/items/d3b6aa8803c62238d990)
[[RESTful API]パスパラメータ、クエリパラメータ、リクエストボディの違いと設計](https://qiita.com/Shokorep/items/b7697a146cbb1c3e9f0b)