こんにちわ！やっとこさ入社１ヶ月半の浦です。
毎年この時期は花粉にやられています。ただただつらいです。鼻の粘膜を焼いてアレルギー反応が起こりづらくする治療もあるようですが、ちょっと怖いのでチャレンジできずにいます。花粉面倒なので、どなたかGWまでタイムリープする方法を知りませんか？

今回のテーマ

さて、現在私は【ODPS】 という、工場受注～生産管理までを一括で担うクラウド管理 システムの開発に携わっています。詳しくは以下のリンクをご覧いただければと思います。
https://imagemagic.jp/service/odps/

クラウド管理システムなので、当然ながらWebサービスです。
TwitterでもYouTubeでも何でもかまわないのですが、Webサービスのエンドポイントの設計って気になりませんか？個人的にはけっこう見ちゃうんですよね。
APIを使う際、URIの設計が悪いと使い方を理解しづらかったり、間違って使ってしまったり・・・。ということで今回は、分かりやすいエンドポイントの設計について考えてみたいと思います。

余計な情報がない

例えば、以下のURIを見てどう思われるでしょうか。

• http://example.com/service/users/get

個人的な突っ込みどころは二つです。

1.「service」が抽象的

大抵「サービス」という単語が出てくると、より具体的な機能を当てはめた単語に置き換える必要があるか、その単語自体不要なことが多いかと思っています。

2. 「get」は不要

HTTPのメソッドで使い分ければいいですね。URIの指すリソースと、そのリソースに対する操作は分離できた方が見やすいです。

単語を省略しない

• http://exapmle.com/sv/u

このURIを見て、どんなリソース・機能にアクセスするのか分かるでしょうか。「sv」は「service」かもしれませんし、「supervisor」かもしれません。「u」も省略し過ぎて「user」なのか判然としませんよね。
人間が見てどのような機能なのか理解できないURIは、タイプミスに繋がります。APIを公開してクライアントにアクセスしてもらうことになった場合、上に挙げたような理解しづらいURIは、クライアントの開発効率の低下に繋がると考えます。

大文字小文字が混在していない

大文字小文字が混在しているとは、例えば以下のようなケースです。

• http://example.com/Users/0123

URIのすべてが小文字に統一されていれば、この単語は大文字だったっけ？と迷うことがなくなります。また、ホスト名の部分はすべて小文字での表記が一般的ですので、それに合わせてすべて小文字にするのが良しとされているようです。

集合は複数形

• http://example.com/user/0123

一見上記URIは、意味も分かりますし適切に思えます。しかし、上記URIの示すところは、「ユーザー」という集合の中の、「0123」というリソースです。データベースのテーブル名は一般的に複数形が適切といわれているのと同様で、集合を表すものは複数形にするのが一般的です。

まとめ

簡単ではありますが、今回は分かりやすいエンドポイントの設計について考えてみました。
エンドポイントの設計にご興味のある方は、ProgrammableWebという様々なAPIをまとめたサイトがお薦めです。各サービスがどのようなエンドポイントになっているか眺めるだけでも勉強になります。
URIの設計に限らずコーディングもそうですが、分かりやすさという観点は忘れずに今後の開発に取り組んでいきたいものです。