WEB APIのURL設計のトレンドはこれだ！WEB APIのURL設計まとめ

APIのURL設計をしようと思い、その前に有名サービスのAPIのURL設計がどうなっているのかについて調べました。
一覧を載せた後に、「多数派なURL設計」を書きたいと思います。

有名サービスのAPIのURL設計

サービス	API URL
Facebook	https://graph.facebook.com/***
Twitter	https://api.twitter.com/1.1/***.json
mixi	https://api.mixi-platform.com/2/***
Tumblr	http://api.tumblr.com/v2/***
GitHub	https://api.github.com/***
Yammer	https://www.yammer.com/api/v1/***.json
Asana	https://app.asana.com/api/1.0/***
Stripe	https://api.stripe.com/v1/***
Dropbox	https://api.dropbox.com/1/***
Flickr	http://api.flickr.com/services/rest/?method=***
Parse	https://api.parse.com/1/***
Twilio	https://api.twilio.com/2010-04-01/***
Pusher	http://api.pusherapp.com/***
Pingdom	https://api.pingdom.com/api/2.0/***
MongoHQ	https://api.mongohq.com/***
Netflix	https//api-public.netflix.com/***
Zendesk	https://***.zendesk.com/api/v2/***.json

apiの記し方

そのURLがAPIであることを表す方法は大きく分けて2種類あります。サブドメインに置き http://api.example.com/ とするか、パスに置き http://example.com/api/ とするか、です。
眺めてみると、サブドメイン派は12サービス、パス派は4サービスで、サブドメインでapiを表現するのが人気のようです。

• サブドメインにapi: 12サービス
• パスにapi: 4サービス

ちなみにPingdomは、サブドメインとパスの両方にapiを記述していて、かなり強くapiを主張しています。

https://api.pingdom.com/api/2.0/***

バージョン指定の仕方

APIが仕様変更した場合に、既存のクライアントに影響を与えないために、URLにバージョン番号を指定するサービスが多いです。バージョンの指定の仕方はかなり個性があります。
versionを表す「v」を置く派が5サービス、置かない派が6サービスで、「v」は置かずに数字だけで表現するサービスが多数派でした。

• vなし: 6サービス
• vつき: 5サービス

バージョン番号ですが、整数派が8サービス、小数派が3サービスで、アップデートごとに整数でインクリメントしていくサービスが多いようです。

• 整数バージョン: 8サービス
• 小数バージョン: 3サービス

TwilioはAPIのリリース日でバージョンを表現していますが、URLが長くなるからか、少数派です。

URL設計のトレンドはこれだ！

https://api.example.com/1/***

こうして実際に眺めてみると、apiの主張をサブドメインに寄せ、無駄な「v」や小数点、拡張子もつけないことでパスをシンプルにまとめつつも、バージョンを添えることでアップデートにも耐えられる実用性も兼ね備えた、実に洗練された美しい設計に感じます。
実際のところ完全にこのURL設計になっているのはParseとDropboxだけなので、各サービスそれなりにオリジナリティがあって、URLを眺めているだけでも楽しいです。

変わり種

GitHubのEnterprise向けのAPIでは、独自ドメインを設定できるようです。

https://yourdomain.com/api/v3/

GitHub自体は、apiサブドメイン+バージョンなしなのですが、この場合はパスにapiを切ってバージョン番号もつけるようです。