Monday, March 10, 2014

拡張可能なWeb APIの設計原則と、バージョン番号を使う理由について

APIのバージョニングは限局分岐でやるのが良い - Hidden in Plain Sightにはブコメしたのですが、Rebuild: 35: You Don't Need API Version 2 (Kenn Ejima)でも本件に言及があったようなので、少し一般論を書いておきたいと思います。


■Web APIの設計原則について

そもそも、良いAPIとはどのような特性をもつものでしょうか? 一般的に、以下の2点が挙げられると思います。
  • 拡張が容易である
  • 拡張時に後方互換性を破壊しない

ウェブの場合は、これに加え、
  • スケーラブルである
  • HTTPに起因する問題に上手に対処できる
ことが求められます。

前2者はウェブに限らない要件です。これを満たす設計手法としては、
  • リクエストおよびレスポンスのパラメータを拡張可能に
  • 互換性を壊す拡張が必要な場合は、関数名を変える
    • 古い関数は従来と同じ機能を提供する
  • ステートフルAPIは、抽象データ型の使用
といった手法が一般的です。

たとえばMicrosoft WindowsのAPIを見ると、多くのリクエストとレスポンス型が拡張可能であり(cbSizeというフィールドで拡張領域を指定する)、非互換な拡張がされたAPIは「〜Ex」という名前をもっており、ステートの表現にはHANDLEという抽象データ型が使われていることが分かります。

これに対し、後2者はウェブ固有の色合いが強い要件です。そして、そのための設計手法として、
  • (出来る限り)ステートレスなAPI
  • 冪等性に対する配慮
が求められる、ということが知られています(したがって、「ステートフルなAPIにおける抽象型の利用」という一般的な設計手法は検討対象外となる)。

以上の2者をまとめると、Web APIを設計する基本原則として、以下の4点を採用するのが良い、ということになります。
  • 拡張可能なパラメータ
    • JSONのような拡張可能なシリアライズフォーマットを用い、拡張可能な形で入出力パラメータを設計する
  • 互換性を壊す必要がある場合は関数名を変更する
  • できるだけステートレス
  • 冪等性に対する配慮
    • よく分からなければ、とりあえずRESTを使う

このような設計をとっていれば、APIを拡張しても後方互換性を確保することができますし、バージョン番号による分岐も必要になりません。


■バージョン番号をURLに含めるべき理由

述べたように、拡張可能なWeb APIの設計において、バージョン番号による分岐という概念は必ずしも必要なものではありません。ですが実際は、それでもバージョン番号をURLに含めるべきだと考えられることがあります。

APIが拡張(ないし変更)されていくということは、すなわち、サーバサイドの提供するAPIの「バージョン」とクライアントアプリケーションが期待するバージョンの齟齬による互換性問題が発生しうるということを意味します。そして、そのような互換性問題は、実行中の良くわからないエラーではなく(データ保存しようとしたらエラーとか最悪ですね!)、明確にトラブルシュートできる、つまり、起動時のバージョンチェックで検出され、ユーザーや管理者に明確に通知されることが望ましいということになります。

実際には、以下のような要件のもとで、確実に機能するバージョンチェック機構が望ましいということになります。
  • クライアントが「廃止された」APIに依存しているかどうかは、サーバサイドでないとチェックできない
  • クライアントアプリケーションの開発者は、しばしば「バージョンチェックを怠る」

もうお分かりでしょうか。この要件を最も単純に実現する手法が、APIのURLにバージョン番号を含めるという手法なのです。APIに対する全てのリクエストにバージョン番号が含まれるため、「クライアント側でバージョンチェックを怠った」がゆえのエラーは発生しようがありません。また、サーバサイドのログにもバージョン番号が残るため、管理者の側で問題の切り分けを要求された場合にも、対処することが容易です。

これが、バージョン番号をAPIのURLに含めるべきと考えられる理由です。必ずしも全ての条件において必要ではないかもしれませんが、一考に値するのではないでしょうか。

なお蛇足ですが、APIのバージョニングについては、サービスとしてしか提供しないソフトウェアの場合は、後方互換性を崩す度にバージョン番号の変更が必要です。また、サーバをソフトウェア製品として提供する場合には、機能拡張を行う度にバージョン番号の変更が必要になります注1(2014/3/11加筆)。ですので、特に後者のバージョン番号発番については、semantic versioningを参考に、MAJOR.MINORのような記法を採用するのが望ましいと言えるでしょう。


参考文献: Webを支える技術 -HTTP、URI、HTML、そしてREST (WEB+DB PRESS plus)

注1: クライアントの機能が特定のマイナーバージョン以降に依存することもあり、かつ、サーバサイドのバージョンがクライアントサイドのそれより古いことがあり得るため

4 comments:

  1. The actual indices, fingers other than the actual hublot replica mere seconds hands, along with the bezel that sports activities the ceramic place for your additional little bit of dark have been in tag heuer replica uk, whilst 2 splashes associated with red-colored, employed for the actual Speedmaster piece of software and also the cartier replica from the main chouronograph hands had been additional. From the individual watchpoint, getting observed all rolex replica sale Aspect From the Celestial satellite wrist watches "live, inch this particular item, combining the actual rolex replica uk colour from the precious metal and also the previously mentioned places associated with red-colored appeared to be a little from rolex replica sale amongst all of those other Darkish, Gray, as well as Whitened Aspect From the Celestial satellite wrist watches. The actual tag heuer replica sale is actually, although, which precious metal causes it to be which tiny bit much more dressy as well as stylish. Right now, the actual cartier replica sale. As the Dark Dark is actually certain enjoyable, the actual Message Dark is actually fascinating because of its lume-craze, and also the Sedna Dark is really a little bit much more stylish compared to relaxation, the actual Classic Dark might be probably the most coherent as well as intriguing brand new style from the great deal.

    ReplyDelete
  2. Harga rak kosmetik dari kayu tentunya sangat mahal, yaitu hingga jutaan rupiah. Nah untuk anda yang tempat kosmetik yang unik namun harganya murah maka sebaiknya memakai rak kosmetik dari plastik mika. Rak ini merupakan rak susun yang terdiri dari 4 sap. Pada bagian depan rak kosmetik gantung dari plastik ini terdapa resleting yang memudahkan anda untuk mengambil dan meletakkan kosmetik. Fungsinya juga supaya bisa tertutup rapat untuk melindungi kosmetik supaya tetap bersih dan tidak mudah berdebu. Harga rak kosmetik dari plastik ini di pasaran sekitar 50.000 rupiah saja. Ada banyak warna dan pilihan karakter kartun lucu pada bahan banner rak kosmetik unik dan minimalis ini. Produk organizer rak kosmetik saat ini memang sangat disukai karena murah, praktis, simpel dan minimalis. Apakah kamu juga tertarik untuk beli rak make-up organizer ini?

    ReplyDelete
  3. Salah satu pusat rak sepatu gantung yang dijual grosir maupun ecer adalah fauziyah bag. Ini merupakan produsen yang bikin produk organizer sendiri. Sebagai pusat rak sepatu gantung yang murah meriah, fauziyah bag ini selalu mengedepankan kualitas produk dan kecepatan pelayanan. Jika anda beli sekarang maka akan dikirim hari itu juga. Selain sebagai pusat rak sepatu gantung, disini juga menyediakan beberapa produk organizer lainnya. Pusat rak sepatu gantung berkualitas lihat info disini.

    ReplyDelete
  4. Kami menjual produk organizer rak tas gantung secara ecer maupun grosir. Ini adalah tempat tas dari plastik yang harganya murah meriah dan tentu sangat berkualitas. Rak tas gantung yang juga dilengkapi dengan resleting ini terdiri dari 5 susun dan masing sekatnya menggunakan kayu triplek. Harga grosir rak tas gantung resleting ini cuma 48.000 rupiah per biji. Grosir rak tas gantung murah berkualitas klik penjelasan selengkapnya.
    Bagi para muslimah yang membutuhkan tempat jilbab yang nyaman dan dijamin tidak mudah kusut maka pakailah rak jilbab organizer, harganya cuma 15.000 rupiah saja. Ada hanger besi bertingkat 5 susun dan dilengkapi cover plastik yang tebal. Tentunya produk rak jilbab organizer ini dijamin bagus dan tidak mudah rusak. Rak jilbab organizer murah meriah baca info selanjutnya.
    Kisaran harga tongkat madura itu antara 80.000 sampai 150.000 rupiah saja dan tentu bukan sekali pakai saja karena tongkat madura ini bisa dipakai beberapa kali bahkan ada yang sampai 6 bulan lamanya. Meskipun harga tongkat madura murah meriah, khasiat dan manfaatnya tidak diragukan lagi.Telah banyak para wanita yang membuktikan langsung keampuhan produk ini. Tongkat madura murah dan ampuh baca halaman terkait.

    ReplyDelete