HTTP API進化に関するベストプラクティス

作者 Dilip Krishnan , 翻訳者 尾崎 義尚 投稿日 2012年1月25日

セクション

エンタープライズ・アーキテクチャ,

設計/アーキテクチャ,

デベロップメント

トピック

HTTP ,

REST ,

W3C ,

エンタープライズアーキテクチャ ,

Architecture ,

プログラミング ,

仕様

原文(投稿日：2012/01/18)へのリンク

HTTP API発展性へのベストプラクティスのタイトルが示すようにBenjamin Carlyle氏は、HTTP APIに関するシステムを設計する際の原則とプラクティスを定義した。システムとは、拡張可能で、時間とともに進化するものである。彼は、アーキテクチャスタイルのRESTと、HTTPを経由して公開されるプログラム可能なHTTP APIとの違いを示すことからはじめた。

HTTP APIは、特定のサービスに対するプログラマ指向のインターフェイスであり、RESTfulサービスコントラクト、リソース指向アーキテクチャ、URI空間と言った別名で知られている。

細かく言うと、多くのHTTP APIは、インターフェイスの"標準"で要求された厳密な意味での定型インターフェイス制約に制限されない。[…]

まず彼は、時間をかけて進化を決定するAPI構築の様々な要素を特定することからはじめた。一般的にAPIの進化は、クライアントとサーバーの互換性、特にAPIの変更による上位互換と下位互換に影響する。頻繁な変更による改善:

1. APIで使われるメソッドの一般的なセマンティクスには、例外的な条件と他のメタデータが含まれる
2. APIで使われるメディアタイプの一般的なセマンティクスには、任意のまたは、すべてのスキーマ情報が含まれる
3. APIで作られるURIのセットには、APIで使われる一般的なメソッドと一般的なメディアタイプの特定のセマンティクスが含まれる

API進化で最新の変更をした状態は、メソッドのセマンティクスである。この記事で説明されているベストプラクティスは、上位および下位互換への変更と、サービスとクライアントはよりゆるやかな方法で進化できるようにするアプリケーションがポステルの法則を認識することである。彼は、互換性の問題を伝えるために可能な限りHTTPエラーコードを使うことを提案している。

ベストプラクティス3:既存のメソッドと下位互換がないメソッドには、新しい名前が選択されるべきである。 - たとえば、メソッドを正しく処理するために理解するべき(セマンティクスを理解する必要がある)新しいメソッドの機能があった場合に新しいメソッド名が選択されるべきである。

ベストプラクティス4:サービスは、理解できない、またはそれらが認識していないコンポーネントのヘッダを無視するべきである。プロキシは、それらのヘッダを変更しない、または彼らが変更無しでは理解できないコンポーネントは変更せずにパスするすべきである。

[…]

ベストプラクティス7:新しいステータスには、既存の、状態を理解できる粒度の、数値の範囲内のステータスコードが割り当てられるべきである。

[…]

ベストプラクティス9:新しいステータスが、400 Bad Requestや500 Internal Server Error以外の既存のステータスのサブセットだった場合、既存のステータスの意味を改良して、レスポンスヘッダに追加情報を追加するよりも、新しいステータスコードを割り当てた方がよい。

彼は、サーバーとクライアントのメディアタイプに関する対称的な性質に関して重要な違いについて指摘している ...

[…] クライアント・サーバー間の非同期なメソッドとステータスとは違い、メディアタイプは一般的にリクエストとレスポンスのペイロードとして、どちらの方向に移動するのにも適している。このような理由から、このセクションでは、クライアントとサーバーについてではなく、送信者と受信者について話します。

... メディアタイプに関して、ベストプラクティスの基本的なフォームとして認識されている。

[…]

ベストプラクティス11:ドキュメントのバリデーションは、ベストプラクティス10を満たして、バリデーションロジックが同じバージョンか、それ以降のバージョンのAPIでドキュメントの送信者として書かれた場合のみ失敗する可能性がある。

ベストプラクティス12:メディアタイプの設計目標で既存のメディアタイプのスキーマに新しい情報を追加できる場合、それを追加するべきである。

彼は、送信者と受信者間の互換性を管理するためにContent-TypesとAcceptヘッダを使うことを提唱している。

HTTP APIはメディアタイプスキーマの変更の上位互換に利用する。要求されたスキーマ、または新しいクライアントによって提供された互換性のない変更を伴う新しいメディアタイプ。継続して要求されており、前からのクライアントによって提供された古いメディアタイプ。クライアントとサーバーのメディアタイプがアップグレードされ、新しいメディアタイプが対応されるまでの間のサポートに必要である。

彼の意見では、URLのリソース空間の変更はサーバー中心の問題であり、ハイパーメディアの制約設計によって、 クライアントで互換性の問題を起こすべきではない。彼は、クライアントリクエストをサーバーのインスタンス/サーバーに適切にルーティングするためにクッキーの利用を提言している。

汎用メソッドやメディアタイプを処理する必要はなくなったが、様々な汎用メソッドを使うとき、特定のセマンティクスを持つ特定のURLを処理する必要がある。   […] 以下は、サービスコントラクトに関する、サーバー中心の見方である:

• GET /invoice/{invoice-id}, invoice-idの請求書(invoice)をapplication/invoice+xmlで返す
• GET /invoice/{invoice-id}/paid, invoice-idの請求支払い(invoice paid)ステータスをtext/plain (xsd:boolシンタックス)で返す。
• PUT /invoice/{invoice-id}/paid, invoice-idの請求(invoice)に対する、請求支払い(invoice paid)ステータスをtext/plain (xsd:bool シンタックス)でセットできる

加えて彼は、サーバーサイトURL空間を変更することができるクライアント機能に関するベストプラクティスも示した。

ベストプラクティス19: サーバーは、クライアントを古いサーバーに固定しておくのか、クッキーやそれに似たメカニズムを使って新しいサーバーにアップグレードするのかを追跡し続けるべきである。

ベストプラクティス20: クライアントは、HEADまたはGETリクエストから応答がないときの、サーバーからのリダイレクトステータス応答を追跡するべきである。[RFC2616]

ベストプラクティス21:URL空間を再設計する場合、古いURLと同じセマンティクスでURLを用意し、古いURLから新しいURLにリダイレクトするようにする。

この記事は、時間をかけて進化するHTTP APIシステムを可能にする基本原則を提供する。このトピックをより深く知りたい場合、元の記事を参考にして欲しい。

• 次へ >