星屑アトリエ

並行世界のエンジニア界にいる端くれ一般ぴーぽー。いろいろ備忘録。

Web API トレーニング 02 -エンドポイント設計編-

エンドポイントとは

これ

http://fugahoge.com/v1/articles
というURLがあったとして、ホスト名とエンドポイントで分けることができる。

ホスト名は
http://fugahoge.com/v1
になって、

エンドポイントは例えばこうなる
/articles

まぁベースとなるURLがホスト名、後に参照したいリソースの集合をエンドポイントと呼ぶみたい。

エンドポイントを考える

エンドポイントは、「データの集合」「個々のデータ」についてHTTPメソッドで操作していくことを表すように設計する。

  • リソースの集合、単体のリソースとしてURIを設計する
  • HTTPで定義されたメソッドで操作する。

個人的には、 何を、どうする? っていうイメージで設計するものかなと。

具体的にいえば、
「リソースとその集合」を、「HTTPメソッドで操作」する
これに帰結するかなと思ったので、そういう意識でエンドポイント作りたい

エンドポイントを設計するにあたっての留意事項

  • 複数形の名詞を使う
  • 利用する単語に気を使う
  • スペースやエンコードを必要とする特殊文字は使わない
  • 単語をつなげる場合は考える

リーダブルコードに通づるところg(ry

検索とクエリパラメータ

GETメソッドによく付けるなぁと。

http://fugahoge.com/v1/users

例えば上記がユーザーを取得するAPIのエンドポイントだとして、
単に叩いたら全ユーザーを取得してしまいかねない。
そこでクエリパラメータと呼ばれる実行時の条件をエンドポイントの後ろにくっつけるようにしてもらう。

ページネーション

あるデータの集合の一部分を取得する、といった時に使う考え方。
データを、 どこから、どれくらいの量を 取得するのか、というのを指定する。

よくある例としては、

どこから どれくらい
per-page page
offset limit

こんな感じのものが多い

次回

次は絶対位置でデータを取得しようねの話