WebAPIを設計するときに以下のようなエンドポイントを用意したい
- idを指定して、単一のリソースを返す
- queryを指定して、単一のリソースを返す
- idを複数指定して、複数のリソースを返す
例としては、地図上で表す東京タワーなどのランドマークのリソース（名称、位置情報、説明）にIDを振ったとして
1.はIDで１つのランドマークを検索
2は緯度経度で１つのランドマークを検索
3.は複数のランドマークを検索
というようなことがしたい
ここで迷ったのが、URIは単数形と複数形のどちらにすべきか？
というのもの
Enchant の開発者である Vinay 氏が書いた記事「Best Practices for Designing a Pragmatic RESTful API」 や www.vinaysahni.com
ZalandoのRestfulAPIガイドでは opensource.zalando.com
単数のインスタンスを複数形で表す場合でも「一貫して複数形を使う」とあり、その考え方が広く知られている
しかし、これを忠実に守った場合、2.と3.を共存させることができない
どちらも/landmarks/?someParams=xxxxxというURIになるが、レスポンスが単一のリソースと複数リソースで異なるので
2.を複数に返すようにして、使う側で１要素目だけを使うというようにするのにも違和感がある（緯度経度指定して複数のランドマークが返されるとは思わない）
解決策：単数形のURIを用意してしまう
何の裏付けもないが、エンドポイントの特性上、単数形のURIを用意してしまうのがよいのではないかという結論になった
つまり、先述した２つのAPI設計ガイドとは異なり、単一のリソースを返却する場合は単数形のURIで、複数のリソースを返却する場合は複数形のURIにする
/landmark/13: LandmarkResource/landmark/?lat=xxxx&lon=yyyy: LandmarkResource/landmarks/?ids=13,14,15: Array
ガイドから外れたことをするのは怖いが、これで共存とAPIのわかりやすさが解決できたとおもうので、この方針で進めてみる
気付き
もし仮に設計ガイドに従って先に1.と2.を複数形で定義して公開もしてしまっていた場合
3.をあとから追加する際にちょっと面倒なことになっていたと気付いた
2のエンドポイントを変更しなくてはならないか、返却する型を変えなくてはならないから
なので、１つの気づきとしてURIの設計の際にノーシンキングで複数形になっているのは、あとあと変更が面倒なので注意した方がよいかも
