Web API: The Good Partsを読んだので「良いURI」についてまとめた

はじめに

APIの勉強のために、Web API: The Good Partsを読みました。平易な日本語で書いてあるので、読みやすかったです。
とはいえ、何度も本を読み返すのは大変なので、自分用まとめも兼ねて書こうと思った次第です。

1個1個まとめていくと結構な量があるので今回は「良いURI」とは、についてまとめました。
APIのエンドポイント(URIのこと)を考えるときにURIのことも一緒に考えないといけないので、基礎編として「良いURI」についてまとめました。
本でいうと2.2に書いてあります。

この記事も参考に

Web API: The Good Partsの他のまとめ記事もここに載せておきます。

• 2.6: Web API: The Good Partsを読んだので「OAuthの仕組み」についてまとめた
• 3章: Web API: The Good Partsを読んだので「レスポンスデータの設計」についてまとめた
• 4章: Web API: The Good Partsを読んだので「HTTPの仕様」についてまとめた
• 5章: Web API: The Good Partsを読んだので「設計変更しやすいWeb API」についてまとめた

記事を書く順番は章ごとではなく結構バラバラです。

URIとは

こちらの記事が分かりやすいです。

URIとよく聞くURLは同じものではなく、URIの部分集合にURLがあります。
詳細は上の記事を見ていただければと思いますが、正式名称がURIということですね。

URIはリソースの場所や名前を示すものであり、URLはURIのうち主に場所を示すもののことです。

http://hogehoge.co.jp

みたいなのはURIでもありURLでもあります。

良いURIとは

APIのエンドポイントはURIなので、まずURIの設計を考えることが大事になります。
それでは良いURIの重要な原則には以下のようなものがあります。

覚えやすく、どんな機能を持つURIなのかひと目でわかる

分かりやすいものであることで、間違って使われる確率も下がり、間違ったアクセスが大量に行われ、サーバに負荷がかかるという問題を避ける事ができます。

では、覚えやすくて分かりやすいURIとはどういったものでしょうか？
本には以下の6つがあると書いてあります。

• 1. 短く入力しやすいURI
• 2. 人間が読んで理解できるURI
• 3. 大文字小文字が混在していないURI
• 4. 改造しやすい(Hackableな)URI
• 5. サーバ側のアーキテクチャが反映されていないURI
• 6. ルールが統一されたURI

1. 短く入力しやすいAPI

読んで字のごとくです。短く入力しやすい＝シンプルで覚えやすいことにつながります。

http://api.example.com/service/api/search
http://api.example.com/search

上と下どっちがいいでしょうか？
上は、apiという言葉がホスト名とパス名の両方にある上に、serviceという似たような言葉があるので削ることが出来ますね。下でも基本的な情報は変わらず、searchするAPIだということがわかると思います。

短くてシンプルな方が、理解しやすく、覚えやすく、そして入力間違いも少なくなるでしょう。

2. 人間が読んで理解できるURI

まず例を見てみましょう。

http://api.example.com/sv/u/

apiはともかく、svとuは何のことでしょうか？
私はuとsvを見て何のことかパッとわかりませんでした。(本ではuはuser、serviceのことかもしれないと書いてありました)

むやみに 省略をしないことが大事になります。

もう１つ別の例を見てみましょう。
ECサイトで何らかの製品情報を取得するためのAPIを考えます。

http://api.example.com/products/12345
http://api.example.com/productos/12345
http://api.example.com/seihin/12345

さて、どれが一番分かりやすいでしょうか？言うまでもありませんが、英語である一番上ですね。
このように英語以外の言語を使わないことは当たり前のようですが大事になります。

他に英語であったとしても日本人からすると正確なニュアンスがわからない言葉があったりします。例えば、findとsearchは両方探すという意味ですが、ちゃんとした違いは分かるでしょうか？

このように、ネイティブでない人だと怪しい単語を使ってしまいがちです。
こういう問題を解決するには、ProgrammableWebのAPIを見て、実際に他のAPIでどんな単語を使われているか知るのがいいでしょう。普通にWebサイトを作るときでも有名なサイトのURI構成を見て勉強してみるのがいいとおもいます。

その他、理解しやすいURIにするためには スペルミスをしないことがあげられます。しっかりスペルチェックを行うようにしましょう。

まとめると人間が読んで理解できるURIは以下の３つになります。

1. むやみに単語を省略をしない
2. 単語には英語を使う
3. スペルミスをしない

3. 大文字小文字が混在していないURI

単純に大文字と小文字が混じっていると読みにくいのでやめようね、という話です。
もし大文字、小文字が違うだけのURIがあった場合、それは違うものとみなして404エラーを返すサービスが多いようです。

基本的にエンドポイントは統一のあるものにしましょう。

4. 改造しやすい(Hackableな)URI

例を見てみましょう。

http://api.example.com/v1/items/123456

上記のようなURIは123456の部分を変えれば、別のアイテムの情報にアクセスできることが予想できますね。

このようにある程度予想できるURIだと、ドキュメントを見なくても開発を進められることが出来ます。

5. サーバ側のアーキテクチャが反映されていないURI

例えば、

http://api.example.com/cgi-bin/get_user.php?user=100

このAPIはPHPで書かれていてCGIで動作しているということが分かってしまいますが、こういう情報はAPIの利用者的には知る必要がないです。

サーバ側のアーキテクチャが反映されないようなURIにする必要があります。

6. ルールが統一されたURI

以下の例を見てみます。

BAD

# 友達の情報の取得
http://api.example.com/friends?id=100

# メッセージの投稿
http://api.example.com/friend/100/message

上の例だとクエリパラメータでidを指定している一方で、下の例はURIのパスの中に入れる形になっています。friendも単数形が使われていたり複数形が使われていたりしていてばらばらになっていますね。messageも単数形が使われています。

こういうバラバラなルールは統一したほうが良いのはいうまでもありません。

GOOD

# 友達の情報の取得
http://api.example.com/friends/100

# メッセージの投稿
http://api.example.com/friends/100/messages

さて、これはAPI問わず、良いURIの設計をするために適用可能なものです。
Railsは上のようなURI設計がしっかりとされていますね。

おわりに

いかがでしたでしょうか。
普段RailsのようなWebアプリケーションフレームワークを使っていると、綺麗なURIを見慣れがちですが、APIはもちろんWebサイトのような静的なものを作る際にも役立つのではないでしょうか。
詳しくはWeb API: The Good Partsを読んでいただければと思います。