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

APIのURL設計をしようと思い、その前に有名サービスのAPIのURL設計がどうなっているのかについて調べました。

一覧を載せた後に、「多数派な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を切ってバージョン番号もつけるようです。

About katty0324

One comment

Leave a Reply

Scroll To Top