はじめに

この記事は普段バックエンドエンジニアの方に作ってもらっている「WEB APIってそもそもなんだろう」という疑問から執筆しています。

「WEB API The Good Parts(水野　貴明　　著)」を参考に自分なりにまとめアウトプットしていきます。
ぜひフロントエンドエンジニアの方で同じ疑問を持っている方は読み進めてみてください。

対象者

この記事は下記のような人を対象にしています。

WEB APIについて何も知らない方
フロントエンドエンジニアでWEB APIの触りの部分しか知らない方

それでは早速アウトプットに入っていきます。

そもそもWEB APIって何？

"Application Programming Interface"の略で、大きなデータの塊を外部から呼び出すための仕様のことを指します。

そしてWEB APIを使うと以下のようなJSON形式でのデータ取得が可能です。

[
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  },
  {
    "userId": 1,
    "id": 2,
    "title": "qui est esse",
    "body": "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla"
  },
  {
    "userId": 1,
    "id": 3,
    "title": "ea molestias quasi exercitationem repellat qui ipsa sit aut",
    "body": "et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut ad\nvoluptatem doloribus vel accusantium quis pariatur\nmolestiae porro eius odio et labore et velit aut"
  }
]

api設計が必要になってくる6つのパターン

公開しているWebサービスのデータや機能のAPI公開
他のページに貼り付けるウィジェットの公開
モダンなウェブアプリケーションの構築
スマートフォンアプリケーションの開発
ソーシャルゲームの開発
社内システムの連携

SNSサービスのapi設計

機能
ユーザー登録、編集
友達の検索、追加、削除
友達の間でのメッセージのやりとり

上記のような簡単なSNSサービスがあった場合まずユースケースを洗い出します。
すると以下のように必要なAPIが列挙できます。

ユーザー登録
ログイン
自分の情報の取得
自分の情報の更新
ユーザー情報の取得
ユーザーの検索
友達の追加
友達の削除
友達の一覧の取得
友達の検索
メッセージの投稿
友達のメッセージの一覧の取得
特定の友達のメッセージの取得
メッセージの編集
メッセージの削除
友達の近況の一覧
特定のユーザーの近況の一覧
近況の投稿
近況の編集
近況の削除

APIエンドポイントとは

「エンドポイント」という言葉自体、文脈によってさまざまな使い方をされるそうですが、WEB APIにおけるエンドポイントとはAPIにアクセスするためのURIを意味します。

＊URI：URLとURNの総称
＊URL：Web上の住所
(例：https://github.com/)
＊URN：Web側で認識されている名前
(例：Amazonの書籍で見かける、「ISBN」から始まる英数字の羅列のようなもの)

エンドポイントの設計

良いURIの設計の基本原則
覚えやすく、どんな機能を持つURIなのかが一目でわかる
だそうです。

またこれを具体化させると以下の6つになります。

短く入力しやすいURI
人間が読んで理解できるURI
大文字小文字が混在していないURI
改造しやすいURI
サーバ側のアーキテクチャが反映されていないURI
ルールが統一されたURI

短く入力しやすいURI

http://api.example.com/service/api/search

このURIはサービスの検索apiであることはわかります。
しかし同じ認識を持たせたままもっと短くすることが可能です。

http://api.example.com/service/search

人間が読んで理解できるURI

http://api.example.com/sv/u/

上記のようなエンドポイントは辞めましょう。
短くはなってしますが全く理解できないはず。。。

大文字小文字が混在していないURI

http://api.example.com/Users/12345
http://example.com/API/getUserName

上記のようなエンドポイントも良くありません。
基本的に全て小文字を使ってエンドポイントは表記します。

改造しやすいURI

「改造しやすいURI」とはURIを修正して別のURIにするのが容易であることを指します。

良い例

http://api.example.com/v1/items/123456

ダメな例

// id:1~300000の範囲のとき
http://api.example.com/v1/items/alpha/:id

// id:400001~500000の範囲のとき
http://api.example.com/v1/items/beta/:id

// id:500001~700000の範囲のとき
http://api.example.com/v1/items/gamma/:id

// id:700001~の範囲のとき
http://api.example.com/v1/items/delta/:id

上記の「ダメな例」のエンドポイントの場合、クライアント(フロント)側ではいちいちidによって場合分けをしないといけずかなり面倒なことになってしまいます。。。

サーバ側のアーキテクチャが反映されていないURI

サーバー側のアーキテクチャとは、例えばどんなサーバソフトウェアを利用しているか、どんな言語を使って実装を行なっているか、サーバサイドのディレクトリやシステム構成がどうなっているかということを指します。

×良くない例

http://api.example.com/cgi-bin/get_user.php?user=100

上記のようなエンドポイントは「APIが恐らくPHPで書かれていて、CGIとして動作しているんだろうなぁ」というのが一目で分かってしまいます。

ただこうした情報はAPI利用者にはまったく関係ありません。むしろこういった情報はサーバーの脆弱性を突こうとしている人たちに情報を与えてしまっています。

そのためアーキテクチャの特定を容易にしてしまうのはセキュリティ的にもよろしくありません。

ルールが統一されたURI

×良くない例

// 友達の情報の取得
http://api.example.com/friends?id=100

// メッセージの投稿
http://api.example.com/friend/100/message

上記は統一されておらずかなりみづらいと思います。
以下はどうでしょう？

○良い例

// 友達の情報の取得
http://api.example.com/friends/100

// メッセージの投稿
http://api.example.com/friend/100/message

かなり見やすくなったと思います！

HTTPメソッドとエンドポイント

メソッド名	説明
GET	リソースの取得
POST	リソースの新規登録
PUT	既存リソースの更新
DELETE	リソースの削除
PATCH	リソースの一部変更
HEAD	リソースのメタ情報の取得

最後に

フロントエンドエンジニアとして働く中でエンドポイントは全てバックエンドエンジニアが作って下さっていますが、こういった背景のもとで作られているんだと大変勉強になりました。

まだ書籍も途中なので引き続きアウトプットしていきます。

もし何かあればコメントしていただけると助かります！