Web API トレーニング 04 -エンドポイント設計編-
クエリパラメータとパスに仕込んでおくパラメータについて
クエリパラメータってなんだ
このパスのうち、
http://fugahoge.com/search?id=12345
?id=12345
と指定している部分。
URLに直接パラメーターをつけることができる仕組み。
パスに仕込んでおくパラメータってなんだ
エンドポイントの設計方針として、
「リソースを表現する」というのがある。
で、データはリソースそのものであるから、パスに予め仕込めるようにしていいんじゃないのか、っていう話
http://fugahoge.com/user/12345
両者の使い分け
- 一意のリソースを表すのに適した・必要な情報・条件であるかどうか
- 省略可能かどうか
ということらしい。
例えば、ユーザーをUserIDで取得したい、といった場合は、UserIDを指定することで、参照したいユーザの情報一式が一意に定まるので、パスに仕込んでおくほうがいい。
一方で、アクセストークンなどはクエリパラメータとして仕込むのがいいとのこと。
アクセストークンは、「リソースを参照する」ことが目的ではなく、「ユーザーを認可する」ことが目的で、リソースそのものとは無関係だから、パスに仕込んでしまうのは直感的じゃないのかなぁと。
省略可能かどうか、の話について。
例えばユーザーのリストを取得したい、といった場合に、リストを全部取得する、ということはなくて、「条件をつけて検索する」ことが多い。
また省略した場合はデフォルトの条件をつけて検索することが多いので、この場合は、クエリパラメータとして表現するのが妥当。
ここからは自分の解釈ですが、
- 既存のリソースを参照する場合 => パスにパラメータを仕込む
- 条件をつけて「絞り込み検索」を行う時や、一意のリソースを直接参照する目的ではないAPIの場合 => クエリパラメータ
とするのかなと、考えたりしてます。
次回
今まではエンドポイントの設計を見てきたので、今度は、
http://fugahoge.com/v1/...
と、エンドポイントで共通して使われる最初のホスト名についての設計について、勉強考察してみたいと思いますー！
