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

10 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
  5. Manfaat dan khasiat bawang putih tunggal sangat banyak. Anda bisa searching di google tentang manfaat bawang putih tunggal untuk kesehatan dan kecantikan. Bawang putih tunggal berbeda dengan bawang putih biasa karena ini hanya memiliki satu siung saja. Di pasaran harga bawang putih tunggal lebih mahal dari bawang putih biasa karena khasiat dan manfaat bawang putih tunggal sangatlah banyak. Kandungan senyawa di dalamnya juga sangat beragam. Manfaat bawang putih tunggal untuk menyembuhkan penyakit klik tautan ini.
    Wajah yang berminyak dan berjerawat tentu akan terlihat kusam dan tidak terawat. Pastinya orang yang memiliki wajah berminyak akan merasa minder ketika bertemu dengan orang lain. Namun anda tidak usah khawatir sebab banyak cara mengatasi wajah berminyak dan berjerawat agar wajah bisa tampil cantik mempesona. Tips cara mengatasi kulit wajah berminyak dan berjerawat ini bisa menggunakan masker wajah dengan bahan yang alami dan tradisional. Cara mengatasi wajah berminyak dan berjerawat artikel selengkapnya.
    Info kesehatan terlengkap dan perawatan kecantikan dengan menggunakan bahan alami tradisional serta diet sehat yang ampuh menurunkan berat badan baca link ini.
    Salah satu cara mencegah diabetes yang ampuh adalah dengan menerapkan gaya hidup sehat dan pola makan yang juga menyehatkan. Diabetes ini bisa dicegah jika kita tidak lagi mengkonsumsi makanan yang banyak mengandung lemak dan juga harus rutin melakukan olahraga. Ini adalah cara mencegah diabetes yang paling ampuh karena dengan melakukan itu maka aliran darah dan juga glukosa darah akan normal. Cara mencegah diabetes dengan pola hidup sehat read more.

    ReplyDelete
  6. Produk tempat sepatu yang harganya murah meriah adalah rak sepatu gantung organizer yang terbuat dari plastik. Ini adalah rak sepatu gantung murah yang terdiri dari 10 susun dan dilengkapi dengan penutup resleting. Harga rak sepatu gantung murah di toko online cuma 65.000 rupiah saja per biji. Dan bila membeli secara grosir rak sepatu gantung murah maka akan mendapatkan potongan diskon. Jenis rak sepatu minimalis yang berkualitas lihat link berikut.
    Harga grosir rak tas gantung resleting di pasaran online cuma 48.000 rupiah, namun pembelian minimal satu lusin. Ini dikhususkan bagi para distributor dan reseller yang ingin berbisnis rak tas gantung murah tapi berkualitas. Ketebalan plastik mika pada rak tas ini 0,20 mm. Desain rak tas gantung hello kitty resleting ini terdiri dari 5 susun dan masing-masing sekatnya memakai triplek. Jual grosir rak tas gantung resleting tertutup klik selengkapnya.
    Sebaiknya mulai sekarang jangan simpan jilbab di lemari dengan cara dilipat agar tidak mudah kusut. Simpanlah jilbab atau kerudung pada rak jilbab gantung organizer agar bisa tersusun dengan rapi dan jilbab tidak mudah kusut. Jual grosir rak jilbab gantung murah meriah. Anda bisa meletakkan rak jilbab gantung plastik ini di dinding rumah dan rumah pun akan terlihat menarik. Harga grosir rak jilbab gantung termurah baca tautan terkait.

    ReplyDelete
  7. Produsen tongkat madura yang letaknya ada di madura adalah produsen jokotole dan sumber madu. Keduanya berada di kabupaten bangkalan. Tongkat madura asli ini banyak sekali warna dan ukurannya. Namun anda tidak usah khawatir, sebab khasiat dan manfaatnya sama saja. Anda tinggal menghubungi penjual online di interner. Tongkat madura asli khusus untuk wanita baca info berikut.
    Manfaat dari jamu sari rapet asli adalah untuk merapatkan organ intim kewanitaan. Ramuan jamu sari rapet ini terbuat dari bahan alami dan diproses secara higienis dan tradisional sehingga keampuhannya sangat terjaga. Produk jamu sari rapet madura ini dijamin tidak memiliki efek samping negatif sama sekali bagi kesehatan tubuh. Jamu sari rapet untuk organ intim agar kembali perawan lihat halaman artikel.
    Banyak para lelaki yang mencari jamu kuat tahan lama untuk digunakan saat bercinta dengan pasangan. Salah satu jamu kuat tahan lama yang terkenal ampuh mengatasi ejakulasi dini adalah jamu kuat dari pulau madura karena dijamin hubungan seksual tahan lama hingga pagi hari. Khasiat jamu kuat tahan lama madura ini sudah populer hingga ke mancanegar dan banyak para suami yang puas dengan keampuhannya. Jamu kuat tahan lama berhubungan intim di ranjang klik tautan ini.

    ReplyDelete

  8. شركة نقل عفش بالدمام الشرق الاوسط متحصصه فى نقل عفش واثاث بالدمام ونقل العفش بالخبر كما انها توفر شركة نقل عفش بالجبيل والخبر وشركة نقل عفش بالقطيف والاحساء وجميع خدمات نقل العفش والاثاث بالمنطقة الشرقية بارخص اسعار نقل عفش بالدمام وتقدم ايضا شركة تخزين عفش بالدمام والخبر
    نقل عفش بالدمام
    شركة نقل اثاث بالدمام
    شركة نقل اثاث بالخبر
    شركة نقل اثاث بالجبيل

    ReplyDelete