美しいエンドポイントの書き方（前編）

# なにこれ？
APIにおけるエンドポイントとは、APIにアクセスするためのURIのことを指しますが、このURIが非常に見づらかったという経験はありませんか？

開発者にとっては**美しく開発すること**も1つのスキルと考えられます。**美しいエンドポイント**の書き方を知り、ワンランク上のエンジニアになりましょう！

本記事では、エンドポイントの**基本的な設計**に関して記述します。




# 美しいエンドポイントとは？
この記事を読んでいる人から、「**美しいエンドポイント**って言われてもわからない」そんな声が聞こえてきます。

今回お伝えする**美しいエンドポイント**とは、
”**覚えやすく、どんな機能を持つURIなのかがひと目でわかる**エンドポイント”
です。

美しいエンドポイントを作ることで、
+ 間違った利用方法を防ぐ
+ 開発者の生産性向上
+ APIを書いたあなたの評価を上げる

ことができます。


# 基本的な設計
美しいエンドポイントの基本的な設計は次のような点を意識します。
+ 短く入力しやすいURI
+ 人間が読んで理解できるURI
+ 大文字小文字が混在していないURI
+ 改造しやすい(Hackableな)URI
+ サーバ側のアーキテクチャが反映されていないURI
+ ルールが統一されたURI

これらについて1つずつ説明していきます。


## 短く入力しやすいURI
読んで字の如く、短くて、入力しやすいということは、**シンプルで覚えやすい**ことに繋がります。

▼悪い例
```http://api.example.com/service/api/search```
このURIは、「api」や「search」という言葉が入っていることから、何らかの検索ようのAPIであることはわかります。しかし、**「api」という言葉が重複している**、**「service」という同じような概念を持つ言葉が含まれてしまっています**。

▼良い例
```http://api.example.com/search```
このURIでも何らかの検索用APIであることが伝えられます。




## 人間が読んで理解できるURI
**人間（全世界の誰が読んでも）理解できるURI**であれば、何をするAPIなのかをURIを見るだけでわかります。

▼悪い例1
```http://api.example.com/sv/u```
「sv」も「u」も何を意味しているのかが伝わりません。「sv」が「service」、「u」が「user」を表しているかもしれませんが、確信を持つには至りません。**短いURIを目指すことで、わかりづらくなってしまっています。**

▼悪い例2
```http://api.example.com/sa-bis/yu-za-```
Webアプリは全世界の人が見れるものなので、日本人にしか伝わらない書き方はやめましょう。

▼良い例
```http://api.example.com/service/user```
全世界の誰が読んでも理解できるように、世界的な共通言語である**英語**を使うのが最も適切です。



## 大文字小文字が混在していないURI
大文字小文字が混在するURIはAPIを**わかりづらく、間違えやすくします。**

▼悪い例1
```http://api.example.com/Users/12345```
`Users`を`users`と、小文字で書いてしまうケースが出てくるでしょう。もしここに小文字で書くという共通認識があれば、間違いを減らすことができます。

▼悪い例2
```http://example.com/API/getUserName```
`getUserName`はキャメルケースで書かれていますが、単語を2つ以上繋げる場合はスネークケース`get_user_name`やスパイナルケース`get-user-name`がよく使われます。




## 改造しやすい(Hackableな)URI
改造しやすいURIとは英語で言うと、"Hackable"、つまり**ハックしやすいURI**ということで、**URIを修正して別のURIにするのが容易である**ことを意味します。

▼悪い例
| IDの範囲 | エンドポイント |
|:-:|:-:|
| 1~300000  | `http://api.example.com/v1/items/alpha/:id`  |
| 400001~500000  | `http://api.example.com/v1/items/beta/:id`  |
| 500001~700000  | `http://api.example.com/v1/items/gamma/:id`  |
| 700001~  | `http://api.example.com/v1/items/delta/:id`  |

DBのテーブルを分割した影響でこのようになっているのかな、と想像もつきます。しかし、このような仕様ではクライアント側はいちいちIDを見ながら場合分けをしなければならず、しかも分割も不規則なため将来の予測を立てることができません。

**こうしたサーバ側の都合はサーバ内で処理をして、利用者にそれを意識させないようにしましょう。**



## サーバ側のアーキテクチャが反映されていないURI
サーバ側のアーキテクチャとは、例えばどんなサーバソフトウェアを利用しているか、どんな言語を使って実装しているかなどです。Webアプリでは、**URIがサーバ側のアーキテクチャやディレクトリ構造を反映する必要は全くありません。**

▼悪い例
```http://example.com/cgi-bin/get_user.php?user=100```
これを見るとこのAPIがおそらくPHPで書かれていてCGIとして動作しているんだろうなあということがわかってしまいます。また、サーバのアーキテクチャがURIから予測できると、**サーバの脆弱性をついて攻撃してくる人もいる**ので注意が必要です。




## ルールが統一されたURI
**ルールとは利用する単語、URIの構造などを意味しています。** WebAPIでは複数のエンドポイントを公開することがほとんどなので、ルールを守って設計していくことが大切です。

▼悪い例
 友達の情報の取得：`http://api.example.com/friends?id=100` 
 メッセージの投稿：`http://api.example.com/friend/100/message`  
上記の例ではある友達の情報を取得するAPIにはfriendsと複数形が使われていて、しかもIDはクエリパラメータで指定するようになっています。しかしメッセージに関してはfriendやmessageと単数形で、しかもIDはURIのパスに入れる形になっています。

▼良い例
 友達の情報の取得：`http://api.example.com/friends/100` 
 メッセージの投稿：`http://api.example.com/friends/100/messages`  





# 最後に
美しいエンドポイントには共通点があり、広く使われているようなサイトのエンドポイントは美しく設計されていることが多いです。
今回の記事を参考に、美しいエンドポイントを設計できるようになり、美しいエンジニア(?)になりましょう。


# 参考文献
今回の記事は、"Web API: The Good Parts"を参考にさせていただきました。