【REST API】APIでURL(エンドポイント)を決める際のルールとは?

Pocket

今回はAPI設計におけるエンドポイントの決め方について業務で悩むことがあったので参考書をもとに勉強したのでまとめていきます!

特に未経験〜業務経験半年の駆け出しエンジニアにとって知っておくべきAPIのルールを書いていきます!

 

使用した参考書は「WebAPI The Good Parts」になります!

Web APIとは?

 

著書の中でWebAPIとはHTTPプロトコルを利用してネットワーク越しに呼び出すAPIと定義しています。

 

簡単に言うと、あるURLにアクセスすることでサーバー側の情報を書き換えたりサーバー側に置かれた情報を取得できたりするんです!

もっと簡単に言うと、URLを叩いたら欲しい情報だけを取得してくれる機能のことですね。

 

つまり、APIには指定されたURLを使用するので、URLについては特に慎重に考える必要があります。

 

APIのエンドポイントとは?

 

エンドポイントとはURIのことです。

前章で説明したようにAPIにはURLが重要になってきます。

 

URLの参考例

本ブログのURLを参考

https://freelife1.com/

 

エンジニアの場合はこのURLを設計書に基づき記述していくことになるのですが、URLの決め方にも色々ルールがありルールに沿っていないURLを書くとベテランエンジニアに叱られてしまいます。笑

 

まずはユーザー情報を取得するAPIとユーザー情報を登録するAPIについてみていきます。

 

一見、URLは統一されていますが使用するHTTPレスポンスは異なりますよね。

ユーザー情報を取得する場合はGET、ユーザー情報を登録する場合はPOSTで叩きます。

 

情報取得と情報登録の処理は同じURLを使用するがHTTPメソッドは異なる

ユーザー取得APIのURL:api.example.com/v1/users  メソッドはGET

ユーザー登録APIのURL:api.example.com/v1/users       メソッドはPOST

 

エンドポイントを決める際の注意点とは?

 

次にエンドポイントを決める際の注意点を紹介します!

これを知っていないと、いざ実務に入ったときに手戻りばかり発生してしまいます。

 

複数形の名詞を利用する

エンドポイントの設計ではusersなど全て複数形の名詞を使ってリソースの集合を表します。

データベース名も一般的に複数形が使用されるのでAPIでも複数形の名詞を使うのが良いとされています。

これ以上深くは書きませんが、そういうものと覚えておいてください笑

 

使用する英単語を理解する

例えば、searchとfindという単語があるとします。

どちらも「探す・見つける」という意味ですがプログラミングの世界では慎重に使用する必要があります。

 

これらの違いについて、searchは「探す場所を目的語にとる」findは「探すものを目的にとる」らしいです!

基本的にAPIのエンドポイントとしてはsearchを採用することが圧倒的に多いです。

 

APIでどの英単語を使えば良いのか迷った場合は類似のAPIがどのような単語を使っているかを複数サイトで比較しましょう。

 

スペースやエンコードを必要とする文字を使わない

APIエンドポイントはひと目でわかるようにすべきです。

エンコードを必要とする文字とは「%E#%B#%%B#%%%#N%」のような文字のことです。

 

まあ、これは説明しなくてもダメな気がしますよね。一見どんな情報を取得するのかわからないですもんね。

 

単語をつなげる必要がある場合はハイフンを利用する

 

エンドポイントで単語を2つ以上繋げる必要がある場合は色々な繋ぎ方があります。

以下ではハイフンとアンダースコアを例にしてみました。

 

単語を繋げる場合

ハイフン           :api.example.com/v1/user-timeline

アンダースコア:api.example.com/v1/user_timeline

 

本書には載っていませんでしたが、実務では単語をアンダースコアでつなげていることが多い気がしますね。

 

APIのエンドポイントについて注意すべきことはこれくらいです。

今回はここまでにします!

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

CAPTCHA