フロントエンドエンジニアのためのWebAPI入門・エンドポイント設計編

はじめに

2021年8月からフロントエンドエンジニアをしております。
フロントエンドエンジニアとして働いているとサーバー周りの知識が疎くなりがちだと思います。
特にAPIの実装はフロントエンドエンジニアでも任されることが多いかと思うので、まとめました。

WebAPIとは

すごくざっくりいうと、別のサービスのデータを取得したりデータを書き換えたりして開発の助けをしてくれるものです。

例えば、Google MapのAPIを使えば、全く関係ない個人のWebサイトでGoogle Map接続しているように目的地周辺の地図を確認したりできます。

これを自前で実装しようとすると、マップのアプリを作るところから膨大なリソースが必要になります。APIを使用することによって、サービスの開発を助けてくれます。

※TwitterやAmazon、YouTube等多くのWebアプリがWebAPIを公開しています。

エンドポイントの設計

エンドポイントとは、API に アクセスするための URI を指します。 ではどのような設計が良いのでしょうか？ 結論以下の観点について意識すると良いです。

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

ひとつひとつ見ていきます。

短く入力しやすいURI

`例 × http://api.example.com/service/api/search`

ここでは、searchが入っているので検索用のAPIということは推測できます。
apiがホスト名に入っているのと、serviceというのもいまいち何を表しているのかわかりません。
ですので、以下のURIにしたほうがシンプルでよいです。

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

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

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

こちらのAPIはURLだけで何を表しているのかわかりません。
先程短いURIがよい書きましたが、URIを設計する場合には、不用意に省略しないことです。
また、URIは世界的な共通語である英語にするのが最も適切です。

大文字小文字が混在していないURI
基本はすべて小文字を使います。

改造しやすいURI

◯ http://api.example.com/v1/items/12346

直感的にIDが12346のアイテムを指していることがわかります。なんとなく、数字の部分を変えれば、別のアイテムの情報にもアクセスできそうと予想できます。
URIの構造は、ドキュメントで管理されるべきですが、直感的に分かることが重要です。

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

×　http://api.example.com/v1/get-user.php?user=100

PHPで書かれているんだろうなと予想できてしまいます。こちらは、URIのアーキテクチャの特定を容易にしてしまい、攻撃を受ける可能性を上げてしまい、NGです。
ちなみにプログラミング言語が異なっていてもAPI通信することができます。

ルールが統一されたURI

ルールとはURIの構造を指しています。 以下の２つの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/friends/100/messages

前者では、複数形単数形がバラバラであり、idをクエリパラメータで指定するなど統一感がありません。
基本的に複数形にするのが良しとされているようです。

参考