本文書では要求レベルのキーワドとして、 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "OPTIONAL" が 使われます。 これは RFC 2119の解釈と同様です。

私たちの「RESTful API ガイドライン」の目的は、「一貫したAPIのルックアンドフィール」の品質水準を定めることにあります。チームはAPIの開発においては、このガイドラインを守っていく責務がありますし、またプルリクエストを投げてガイドラインを進化させていくことが求められます。

これらのガイドラインは私たちの仕事が発展していく限り、ずっと「作成中」のステータス のままでしょう。しかしチームはこれらにしたがい信頼することが、きっと可能なはずです。

変化を続けるガイドラインに対して、次のルールを適用します。

さらには、いったんAPIが外部に公開されたら、全体の一貫性の維持のために、 最新のガイドラインにしたがって、再レビューし変化させていかなければ ならないことを、肝に銘じておかなければなりません。

SOAPインタフェースをもつSOA WebサービスとRESTを比較すると、前者はユースケースに特化した 操作を中心に据える傾向があります。一方RESTはビジネス(データ)のエンティティを、URIで識別されるリソースとして どう見せるか、標準化されたCRUDのようなメソッドで、異なる表現やハイパーメディアを使ってどう操作されうるかを中心に据えます。 RESTful APIは、固有のユースケースからは切り離され、クライアント/サーバの結合を疎にする傾向にあります。 さまざまな新しい業務サービスを構築するために、APIのプラットフォームを提供している(コア)サービスのエコシステムに、 より適したものとなっていきます。 私たちは、その機能がインターネットで提供されるのか、イントラネットで提供されるのかに かかわらず、すべての種類のアプリケーション、(マイクロ)サービスコンポーネントに、RESTfulウェブサービスの原則を適用します。

API設計と利用の重要な原則がポステルの原則です。 ロバストネスの原則 としても知られています。(RFC 1122 も参照ください)

読みましょう: RESTful APIの設計スタイルとサービスアーキテクチャについての読み物がいくつかあります。

前述のとおり、Zalandoは単なるオンラインショップから、価値あるファッションプラットフォームへと 転換しており、ビジネスパートナーのためにSaaP(プラットフォームとしてのソフトウェア)モデル に続く、製品の豊富な集合を提供しています。 企業として私たちは、これらの製品を(内外問わず)顧客に届けたいのです。

プラットフォームとしての製品とは、(公開)APIで提供される機能群です。 したがってAPIの設計は、製品としての原則に基づくべきなのです。

「製品としてのAPI」を掲げることで、サービスのエコシステムはより進化がしやすくなり、 コア機能を組み合わせることによって、新しいビジネスアイデアを早く試すことができるようになります。

APIプラットフォーム上に構築されたイノベーティブな製品サービスと、 オマケとしてAPIが提供されている通常の企業情報システムとでは、 システム統合をサポートしたり、ローカルに最適化されたサーバサイドを実現するところで違いが出てきます。

顧客の具体的なユースケースを理解し、製品として考えAPIの設計のズレとのトレードオフをチェックしましょう。 クライアント側に不要な負担を強いるような、実装の早すぎる最適化を避け、APIの品質とクライアント開発者の使い勝手に最大限の関心をもちましょう。

製品としてのAPIは、(次章で示す)APIファーストの原則と非常に近い関係にあります。 APIファーストは高品質なAPIを、どうエンジニアリングしていくかによりフォーカスしたものです。

APIファーストは、私たちの エンジニアリングとアーキテクチャ原則 の1つです。

手短にいうと、APIファーストは2つの観点を要求します。

コードの外にAPIを定義することで、私たちは早いレビューフィードバックを促し、 サービスインタフェースの設計が、以下に焦点を当てれるような開発の規律にしたいのです。

さらには、標準化された仕様のフォーマットによるAPI定義は、また、

APIファーストの要素はまた、このAPIガイドラインと同僚やクライアント開発者から、 早期にレビューフィードバックを得るための、APIガイドラインと標準化されたAPIレビュープロセスです。 APIの品質を高め、アーキテクチャと設計の調整を可能にし、サービスプロバイダの開発サイクルに クライアントアプリケーションの開発が引きずられないようにするために、私たちにとってピアレビューは重要です。

APIファーストが、私たちの愛する アジャイル開発の原則と反するものではない ことは重要なことです。 サービスアプリケーションは徐々に進化していくように、APIもまた進化していきます。 もちろんAPI仕様は異なるサイクルで、繰り返し進化を遂げていくでしょうし、そうあるべきですが、 それらはみな、ドラフトの状態と、 早期の チームレビューおよびピアレビューフィードバックから始まるのです。 APIが変更されると、実装上の懸念と自動化テストのフィードバックからメリットを得ることもあります。 開発のライフサイクルにおいて、生産的な機能がまだない間も、クライアントと変更の調整を続ける限り 破壊的変更を伴いながらAPIを進化させていくことができます。

したがってAPIファーストは、要求とドメインについて100パーセント理解し、完全なAPIを 定義し、ピアレビューでその確信が得られるまで、コードを書いてはいけない、ということを 意味するもの ではありません 。 一方、APIファーストがサービス統合または本番運用開始の後に、API定義の公開したりピアレビューしたりする バッドプラクティスと衝突があることも明らかです。

早く、できるだけ早くフィートバックを得ることは重要ですが、その前にAPI変更が次の進化のステップへ の足がかりであることを認識し、既にチーム内レビューで確立された(APIガイドライン遵守を含む)一定水準の品質を、 保つこともまた重要です。

あなたはAPIファーストの原則にしたがわなければなりません。

私たちは Open API (以前はSwaggerと呼ばれていたもの)を、API定義の標準として使っています。APIの設計者はAPI仕様ファイルを、可読性向上のため YAML を使って書きます。Open API 3.0 バージョンを使うことを推奨しますが、Open API 2.0 (別名 Swagger 2)もまだサポートした方がよいでしょう。

API仕様はソースコード管理システムを使って、バージョン管理するべきです。一番良いのはAPIの実装コードを同じやり方にしておくことです。

API実装のデプロイと同じタイミングで、API仕様もデプロイするようにします。そうすることでAPIポータルから探せるようになります。

ヒント: Open API 3.0/2.0 を調査するには、 Open API specification mind map を使って探ってみたり、私たちの Swagger Plugin for IntelliJ IDEA を使って最初のAPIを作ったりすることがよい方法です。既存のAPIを調査したり、検証/評価するには、 Swagger Editor が良い出発点になるでしょう。

ヒント: 私たちは GraphQL のガイドラインはまだ提供していません。私たちの技術評価軸であるZalando Tech Radarでは、汎用目的のピアトゥピアなマイクロサービス間のやり取りには、リソース指向のHTTP/REST APIのスタイル(と関連するツールやインフラサポート)に注力した方が良いと評価しています。RESTと比較してGraphQLには大きなメリットが無いが、いくつかの欠点があると私たちは考えます。ですが、GraphQLは特定ターゲットドメインの問題、特にフロントエンド(BFF)およびモバイルクライアントのバックエンドに多くの価値を提供できます。私たちは既にDXインタフェースフレームワークのAPIテクノとジーとしてGraphQLを既に利用しています。

通常、API仕様のファイルは自己記述的です。つまりファイルは ../fragment.yaml#/element や $ref: 'https://github.com/zalando/zally/blob/master/server/src/main/resources/api/zally-api.yaml#/schemas/LintingRequest'. のようなローカルおよびリモートのコンテンツへの参照を含まないようにすべきです。その理由は参照コンテンツが 一般的には 、永続的ではない し、不変でもない からです。 結果としてAPIのセマンティクスが予期せぬ形で変わる可能性があります。

ですが、次のURLで示されるリソースへのリモート参照は使ってもよいこととします。

これらのURLは私たちが管理していて、永続的 で 不変 であることを保証するからです。MUST 成功とエラーレスポンスを規定する で提案するように、このソースを使ってAPI仕様を定義することができます。

API仕様に加えて、APIのユーザマニュアルも提供することは、クライアント開発者(とくにそのAPIを使った開発経験があまりない人)にとってとてもありがたいことです。APIユーザマニュアルは、以下のような観点を記述するとよいでしょう。

ユーザマニュアルはオンラインで公開されなければなりません。API仕様中の #/externalDocs/url プロパティで書かれたリンクを、APIユーザマニュアルに含めるのを忘れないようにしましょう。

API仕様はAPI管理のための、次のOpenAPIメタ情報を含まなければならない。

Open APIの拡張プロパティにしたがい、以下も 定義しなければなりません 。

Open APIはAPI仕様のバージョンを、 #/info/version で指定します。 バージョン情報の共通の意味を共有するために、私たちはAPI設計者に セマンティックバージョン 2.0 の ルール 1 から 8 までと 11 に準拠することを期待します。 それは<MAJOR>.<MINOR>.<PATCH>の形式で、次のような意味を与えます。

追加の注意:

例:

それぞれのAPIは一意でイミュータブルなAPI識別子が与えられます。 API識別子は、Open API仕様の info- ブロックで定義します。 そしてこれは、次の仕様に準拠しなければなりません。

API仕様は発展し、Open API仕様の観点も変わっていくでしょう。 私たちがAPI識別子を要求するのは、API利用者や提供者に 変更のトレースや、履歴、自動互換性チェックのような APIのライフサイクル管理機能をサポートしたいためです。 イミュータブルなAPI識別子によって、APIの発展にともなうすべてのAPI仕様のバージョンを 識別可能になります。 APIセマンティックバージョン情報 や API公開日 を順序性の基準として使うことで、 バージョン や 公開履歴 を一連のAPI仕様として 取得できることでしょう。

注意: 自分で管理するURNを使って、可読性のあるAPI識別子を使うのはよいことではありますが、 APIの進化の過程で、API設計者がAPI識別子を変更したくなる衝動がきっと出てくるので、 UUIDを使っておくことをおすすめします。

例:

それぞれのAPIはAPIの利用が想定されている対象オーディエンスで分類されなければなりません。 それごとに見つけやすさ、変わりやすさ、設計とドキュメントの品質、権限付与などAPIの異なる標準を 容易にするためです。 私たちは、次に示すようなAPIオーディエンスグループを使って、組織や法的な境界で分類しています。

注意: より小さなオーディエンスグループは、より大きなグループに含まれることを意味します。 したがってオーディエンスグループを追加で宣言する必要はありません。

APIオーディエンスは、Open API仕様の info- ブロックにAPIメタデータとして含めます。 そして、次の仕様に準拠しなければなりません。

注意: API仕様につき、オーディエンスは正確に 1つだけ です。その理由は、小さなオーディエンスグループは、大きなオーディエンスグループに含まれるからです。もしAPIの一部が異なる対象オーディエンスを持つのであれば、 API仕様を分割することをおすすめします。たとえ冗長だとしてもです。

例:

すべてのAPIエンドポイントはOAuth 2.0を使ってセキュアにする必要があります。 API仕様におけるセキュリティ定義のやり方は、 公式のOpenAPI仕様 を参照してください。 次に例も示しておきます。

次のコードスニペットは、このセキュリティスキームをすべてのAPIエンドポイントに適用するものです。クライアントのbearerトークンは、scope_1とscope_2のスコープを追加でもたなければなりません。

APIはリソースを保護するために権限を定義しなければなりません。 少なくとも1つの権限が、それぞれのエンドポイントに割り当てられなければなりません。 権限は 前節 で示したように定義されます。

権限のスキーマの命名は、 ホスト名 と イベント型名 の命名に対応しています。 権限名の設計には MUST 権限(スコープ)の命名規約にしたがう を参照ください。

権限の種類が多く細かくなり過ぎて、複雑なガバナンスを強いられることがないよう、 リソース拡張なしで、コンポーネント固有の権限を使うことにこだわりましょう。 大概のユースケースでは、(read と write違いで)特定のAPIへのアクセスを制限することは、荷主か小売か、カスタマか運用スタッフか、といったクライアントの種類によってアクセスを制御するのに十分なものです。 ただ、APIが異なるオーナーには異なるリソースを返すような状況下では、 リソース固有のスコープは意味があるかもしれません。

標準とリソース固有の権限の例を以下に示します。

権限名を定義し、権限をAPI仕様の先頭でセキュリティ定義として宣言したら、 `セキュリティ要求 を記述して、以下のように各API操作に割り当てます。

非常にレアケースですが、API全体または、その内いくつかのエンドポイントが、特定のアクセス制御を必要としない ことがあります。しかし、この場合も uid の疑似アクセス権スコープを明示的に割り当てるようにすべきです。 これはユーザIDで、OAuth2のデフォルトスコープとして常に利用できます。

ヒント: "Authorization" ヘッダを明示的に定義する必要はありません。 セキュリティセクションが定義されていれば、暗黙的にそれは標準ヘッダとなるからです。

Functional naming が権限にもサポートされない限り、 APIの権限名は次の命名パターンに準拠しなければなりません。

このパターンは、以前の定義とも互換性があります。

APIの変更は、すべての利用者の動作に影響がないようにおこなわなければなりません。 通常、利用者はAPIのリリースサイクルからは独立していて、安定性に注力しており、 付加価値をうまない変更は避けようとします。 APIはサービスプロバイダとサービスコンシューマの間の契約であり、一方の都合だけで それを破棄することはできません。

それを実現するための2つの方法があります。

私たちは互換性を維持したAPIの拡張を強く推奨し、バージョニングは最後の手段とします。(以下に示すルールをみてください SHOULD バージョニングを避ける,MUST メディアタイプバージョニングを使う ) サービスプロバイダが従うガイドライン(SHOULD 互換性を維持した拡張をやろう) と コンシューマが従うガイドライン(MUST 互換性維持のAPI拡張を受容できるクライアントを用意する) で、バージョニングなしに(ポステルの法則を胸に)互換性をたもった変更ができるようになります。

注意: 非互換性とは破壊的変更には違いがあります。非互換は変更とは、以下の互換性ルールを満たしていない変更です。破壊的変更は非互換な変更を本番環境へデプロイすることです。したがって今動いているAPIコンシューマをも破壊することを意味します。通常は、非互換の変更は本番環境にデプロイされたとき破壊的変更になりますが、どのAPIコンシューマにも影響を与えないのであれば、破壊的変更をせずに本番環境に非互換な変更をデプロイ可能です。(廃止予定 ガイドライン参照)

ヒント: 互換性の保証は"オンザワイヤー"形式に対して行われます。API定義から生成されたバイナリまたはソースコードの互換性は、このルールの範疇ではありません。もしクライアントの実装がAPI定義の新しいバージョンへ追従するために更新されるならば、コードの変更が必要だと予想されます。

APIの設計者は後方互換性を維持しつつ、RESTful APIを進化させていくために、次のルールにしたがうべきです。

サービスクライアントにはロバストネスの原則を適用すべきです。

サービスクライアントはサービスプロバイダの互換性あるAPI拡張に対して、準備しておかなければなりません。

サービスプロバイダAPIの設計者は、クライアントから受け付けるものについて保守的で正確であるべきです。

未知の入力フィールドを無視しないというのは、ポステルの法則 (The Robustness Principle Reconsidered) から逸脱していますが、これを強く推奨します。 サーバは次のような問題に気付き、サポートするものを明示すべきです。

特定の状況では、(既知の)入力フィールドがどこからも必要とされていなければ、「not used anymore」の記述をAPI定義に書いておくか、サーバがこの特定のパラメータを無視する限りAPI定義から削除するかしましょう。

レスポンスボディには、常に将来の拡張を考慮して、常にトップレベルのデータ構造として(例えばArrayではなく)JSONオブジェクトを返さなければなりません。JSONオブジェクトは属性を追加することによって、互換性を維持した拡張ができます。これがレスポンスの拡張が簡単になる理由であり、例えば後からページネーションを追加したりということが、後方互換性を崩すことなく可能になります。

Map(SHOULD Mapは additionalProperties を使って定義する参照)は互換性のある将来の拡張をサポートしないので、トップレベルのデータ構造としても禁止されています。

Open API 2.0仕様では、オブジェクトのデフォルト拡張についてはあまり仕様化されておらず、 拡張に関しては additionalProperties のように、JSONスキーマキーワードを再定義したものになっています。 私たちの互換性ガイドライン全般にしたがうと、Open APIオブジェクト定義は、JSONスキーマの Section 5.18 "additionalProperties" のようにデフォルトで拡張に対して開かれているとみなすことができます。

Open API 2.0に関していえば、これは additionalProperties 宣言が、オブジェクト定義を拡張可能にする必要がないことを意味します。

APIフォーマットは additionalProperties をfalseと宣言してはなりません。将来的にオブジェクトが拡張できなくなるからです。

このガイドラインはデフォルトの拡張可能性に焦点を当てているのであって、 ある状況下では単なる値として additionalProperties を使うことを否定はしていません。 例えば、 SHOULD Mapは additionalProperties を使って定義する を参照。

列挙型は値の閉集合であり、完全性が仮定されていて拡張は意図されていません。この列挙型のクローズドな原則は、これを拡張しなきゃいけなくなったときに互換性の問題となってあらわれます。これの問題を回避するために、列挙型の代わりに、上限のない値リストを使うことを強く推奨します。

例外として以下の場合は列挙型を使用してもかまいません。

上限なしの値リストを特定するために、次のように x-extensible-enumのマーカーを使います。

注意: x-extensible-enum は、JSONスキーマに準拠していませんが、大抵のツールには無視されます。

RESTful APIを変更するときは、互換性をたもつ方法でおこない、APIのバージョンが新たに作られてしまうことを避けましょう。複数のバージョンはシステムを理解するのも、テストするのも、保守するのも、進化させるのも、運用するのも、リリースするのも全部を複雑化してしまいます。 (こちらも参照ください)

互換性を維持する方法でAPIを変更出来ないのであれば、以下の3つのどれかを選択してください。

さまざまなデメリットがあるので、バージョニングは何としても避けたいところで、私たちは最初の2つのアプローチのみを使うことを強く推奨しています。

APIバージョニングを避けられないのであれば、(URIバージョニングの代わりに、以下に示すように)メディアタイプバージョニングを利用したマルチバージョンRESTful APIを設計しなければなりません。メディアタイプバージョニングは、コンテントネゴシエーションをサポートするので、密結合度合いは緩和されます。したがってリリース管理の複雑さも減少することでしょう。

メディアタイプバージョニング: バージョン情報とメディアタイプは、Content-TypeのHTTPヘッダで与えられます。例えば application/x.zalando.cart+json;version=2 のように。非互換な変更があるときは、リソースに新しいメディアタイプバージョンがふられます。新しいバージョンを生成するために、コンシューマとプロデューサはContent-TypeとAcceptのHTTPヘッダを使ってコンテントネゴシエーションできるのです。注意: このバージョニングはURIやメソッドには適用できません。リクエストおよびレスポンスのコンテントスキーマにのみ適用可能です。

この例では、クライアントはレスポンスの新しいバージョンのみをリクエストします。

クライアントと同様に、サーバもContent-Typeヘッダに新しいバージョンを送る宣言をして レスポンスします。

ヘッダバージョニングを使うべきなのは、以下の点にあります。

ヒント: 非互換の変更が必要になるまでは、通常の application/json メディアタイプのままにしておきましょう。

さらに: APIバージョニングに「正解」はない では、自説にこだわることなく破壊的変更をどう扱うかを、異なるバージョニングのアプローチで全体感を述べています。

URIバージョニングとは、/v1/customers のように、パスに(メジャー)バージョン番号を含ませる方法です。API利用者は、APIプロバイダがデプロイされリリースされるまで待たなくてはなりません。もしコンシューマもまた、ワークフローを追従できるよう(HATEOAS)ハイパーメディアリンクをサポートするのであれば、これはたちまち複雑化します。特にハイパーリンクで結ばれたサービス依存関係のあるところで、URLバージョンニングを使うと、バージョンアップの調整もまた困難です。この密結合で複雑なリリース管理になるのを避けるためには、URIバージョニングは避けたほうがよいでしょう。代わりに(上で示したような)メディアタイプバージョニングとコンテントネゴシエーションを使いましょう。

API(またはAPIのバージョン)を停止する前に、すべてのクライアントに、そのエンドポイントを停止してもよいという同意をとらなければなりません。(移行マニュアルを提供するなどして) 新しいエンドポイントへ移行の手助けをしてください。 すべてのクライアントが移行が完了したら、廃止予定のAPIを停止できます。

もし外部パートナーによってAPIが使われていたら、廃止予定をアナウンスしたあとAPIの現実的な移行猶予期間を定義しなければなりません。外部パートナーはAPIを使い始める前に、この最小の移行猶予期間に同意しなければなりません。

APIの廃止予定は、OpenAPI定義に含まれなくてはなりません。とあるメソッド、パス全体、(複数のパス含む)APIエンドポイントまるごと、いずれにしてもそれらを廃止予定とするならば、メソッド/パスエレメントそれぞれに deprecated: true を設定しなければなりません。 もし廃止予定がより詳細なレベルで必要であれば、影響する要素に deprecated=true を設定したうえで、description に説明書きを加えます。

deprecated に true が設定されたら、クライアントが代わりに使うべきものやAPIがいつ廃止されるのかを、API定義の description に記述しなければなりません。

本番環境で使われるAPIのオーナーは、APIが廃止予定を調整し、コントロールできない 破壊的影響を避けるため、APIが廃止されるまで、廃止予定APIの利用状況をモニタリングしなくてはなりません。 SHOULD API利用状況をモニタリングするも参照ください。

廃止予定フェーズの間、 Deprecation ヘッダを付けましょう。 (draft: RFC Deprecation HTTP Headerをみてください)。 廃止予定日(HTTP Date/Time形式)を値として付けます。

Deprecation ヘッダを付けても、APIを廃止することをクライアントの合意を取り付けたことにはならないことに注意しましょう。

ヒント: ガイドラインの初期バージョンでは、Warning ヘッダを使うようにしていました。しかし、Warning ヘッダはあまりその意味がハッキリしないので draft: RFC HTTP Caching では廃止になるようです。私たちの構文も、 RFC 7234 — Warning header に合っていませんでした。

クライアントはHTTPレスポンスの Deprecation ヘッダをモニタリングし、APIが将来廃止されることがあるかどうかを注視してください。

ヒント: ガイドラインの初期バージョンでは、Warning ヘッダを使っていました。SHOULD レスポンスにDeprecationヘッダを付けるを参照してください。

クライアントは、廃止予定のものを利用し始めてはなりません。

プロパティ名は、ASCII文字列という制限があります。最初の一文字はアルファベットまたはアンダースコアで、 それに続く文字は、アルファベットまたはアンダースコア、数字のいずれかでなくてはなりません。

(links のようなキーワードのみ、 から始まるプロパティ名とすることを推奨します)

理念: 確立された標準は存在しませんが、多くの有名インターネット企業は、スネークケースを好みます。 GitHub, Stack Exchange, Twitterなど。一方でGoogleやAmazonは、- だけでなくキャメルケースも 使っています。同じところからくるJSONが一貫したルック・アンド・フィールとなるように設計するのは 必要不可欠なことです。

Enumの値 (enum または x-extensible-enumで使われる) は、大文字のスネークケース形式を一貫して使う必要があります。 VALUE や YET_ANOTHER_VALUE のように。このすると、プロパティや他の要素との区別がハッキリつくためです。

ここで「map」は、文字列のキーから他の型へのマッピングを意味します。 JSONにおいてこれはオブジェクトとして表現されます。キーと値のペアはプロパティ名とプロパティの値によって 表現されます。 OpenAPIスキーマにおいては(JSONスキーマにおいても同様)、それらはadditionalPropertiesを使って 表現すべきとされます。そのようなオフジェクトは他に定義されたプロパティは持ちません。

mapのキーは、命名ルール 118の意味ではプロパティ名とみなしませんので、ドメイン固有のフォーマットに したがうようにします。 ドキュメントにはmapオブジェクトのスキーマの詳細に、これを記述するようにしてください。 これはそのようなmapの例です。(transactions プロパティがそれにあたります)

実際のJSONオブジェクトは次のようなものです。

複数の値をもつArrayのプロパティ名は複数形にします。これはオブジェクトの名前は単数形にすべきということも暗に示しています。

booleanとして設計されたJSONプロパティは、スキーマ上nullであってはなりません。 booleanはtrueとfalseの2つの値をもった列挙型です。もしnull値をもちたいことがあれば、 booleanの代わりに列挙型を使うことを強く奨めます。 例えばaccepted_terms_and_conditionsがtrueまたはfalseをもつとき、 これはyes/no/unknownの値をもったterms_and_conditionsに置き換えることができます。

Open API 3.x では、プロパティが無い({})かもしれないことと、null ({"example":null})を表すのに、required と nullable を付けることができます。 もし、あるプロパティが required でなく nullable だと定義されていたら(下表の2行目のように)、このルールは、双方を正確に同じ方法で扱えるようにしなければなりません。

次の表は、すべての組み合わせとそれが有効かどうかを示します。

APIの設計者や実装者は、どちらの場合も異なる意味を割り当てたくなるかもしれませんが、表現力が高いことよりも、クライアントがその微妙な違いを理解せず誤って実装してしまうリスクの方がはるかに高いと考えられるので、私たちはこの選択肢には反対です。

例えばミーティングのように、異なるユーザがスケジュールを調整できるようなAPIでは、各ユーザが 選択 しなければならない選択肢をリソースとできます。 undecided と decided の違いは、それぞれ absent と null としてモデル化できる。 null の場合は、 Null object (例えば、{"id":"42"} に対しての` {}` のように)として表すのが安全です。

さらに多くの主要なライブラリは、 null / absent パターンをほとんどサポートしていないか、まったくサポートしてないかという状態です。(Gson, Moshi, Jackson, JSON-B) 特に、強い型付けを持つ言語では、第3の状態を表現するためには新しい複合型が必要なため、この問題に頭を悩まします。Nullable Option / Optional / Maybe 型を使うことができますが、これらの型のNullableな参照を持つことは、その型の目的と完全に矛盾してしまいます。

このルールの唯一の例外はJSON Merge Patch RFC 7396)で、これは null を使ってプロパティの削除を明示的に示しますが、存在しないプロパティは無視されます。つまり変更されません。

Arrayが空であることは [] として曖昧さなく表現できます。

Stringは列挙型で設計された値を表現するには妥当な型です。

日付と日時のプロパティは _at で終わるようにすべきです。よく似た名前のbooleanプロパティと区別できるようになります。

注意: created と modified はガイドラインの以前のバージョンで言及されていました。したがって、このルールより前のAPIでも引き続き受容されます。

RFC 3339 で定義された日付と時刻のフォーマットを使いましょう。

Open API フォーマット の"date-time"はRFCの"date-time"に相当し、`2015-05-28`のして表されるOpen APIフォーマットの "date"は、RFCの"full-date"に相当します。 どちらもspecific profilesで、国際標準 ISO 8601 のサブセットです。

(リクエストとレスポンスの両方で) ゾーンオフセットが使われる可能性があります。 これも標準で定義されているものです。 しかし、私たちは日付に関しては、オフセットなしのUTCを使うよう制限を設けることを 推奨しています。2015-05-28T14:07:17+00:00 ではなく、2015-05-28T14:07:17Z のように。 これはゾーンオフセットは理解が難しく、正しく扱えないことがよくあることを経験上学んだので、そうしています。 ゾーンオフセットはサマータイムを含むローカルタイムとは異なることに注意してください。 日時のローカライズは、必要ならユーザインタフェースを提供するサービスによってなされるべきです。 保存するときは、すべての日時データはゾーンオフセットなしのUTCで保存します。

時々、数値タイムスタンプで日時を表すデータを見かけますが、 これは精度に関しての解釈の問題を引き起こします。 例えば1460062925というタイムスタンプの表現は、1460062925000 なのか 1460062925.000 なのか 判別できません。日時文字列は冗長でパースが必要ですが、この曖昧さを避けるために必要なことなのです。

期間と時間間隔の設計は、 ISO 8601で推奨されている形式の文字列を使います。 (期間については 付録A RFC 3339に文法が含まれます )

機能本位の命名は、あるアプリケーション群の中で、ホスト や 権限、 イベント名 のような各所から利用されるリソースに、整合性をもたせる強力で簡単な方法です。 そうすることで、コンポーネントについての意味のあるコンテキスト情報を 読み手に提供しつつ、名前の一意性も保証できます。 さらにもっとも重要なのは、技術的、組織的な変化の中でAPIを安定した状態が保たれるという点です。

拡大していく オーディエンス とともにAPIがこの利点を享受できるよう、 ホスト名 や 権限名、 イベント名 に関して、 次のような機能本位の命名体系にしたがうことを強く推奨します。

機能本位の命名体系に導くために、 一意な functional-name が各機能コンポーネントに割り当てられます。 それはコンポーネントが属する機能グループのドメイン名からなり、 機能コンポーネントを一意に識別できる短い名前です。

機能の命名パターンの詳細ルールについては、以下のものも参照ください。

APIにおけるホスト名は、以下に示すようにそれぞれ オーディエンス ごとに 定められた機能の命名ルールに準拠すべきです。 (詳細は MUST/SHOULD 機能本位の命名体系を使う の <functional-name> 定義を参照ください)

次に示すアプリケーション固有のレガシーな規約は、 component-internal APIのホスト名に だけ 適用できます。

例:

このルールは具体化されたパスセグメントに適用され、パスパラメータの名前は この限りではありません。 例えば`{shipment_order_id}`は、パスパラメータとしてはOKです。

例:

これは一貫性のためのルールです(他のほとんどのヘッダがこの規約にしたがっているためです)。 (ハイフンなしの)キャメルケースにするのは避けましょう。例外は「ID」のような共通の略語です。

例:

参考: HTTPヘッダは大文字・小文字を区別しない (RFC 7230)

共通のヘッダ と 独自ヘッダ の章に、HTTPヘッダに関する ガイダンスがもう少しあるので参照ください。

ふつうリソースインスタンスのコレクションが提供されます(すくなくともAPIは用意されるべきです)。 リソースがシングルトンである特別な場合が、カーディナリティ1のコレクションと考えます。

たいていの場合、サービスによって提供されるすべてのリーソースは、公開APIの一部です。 それゆえにベースパスであるルート"/"は利用可能にしておくべきです。

もし非公開の内部APIもサポートする必要があるならば(例えばサービスが特定の運用サポート機能のために)、2つの異なるAPI仕様をメンテナンスし、API audienceを提供することを推奨します。 双方のAPIとも /api をベースパスとして使うべきではありません。

私たちはAPIのベースパスを、デプロイ時の可変な設定の一部として考えています。したがって、この情報は、 server object に定義されなければなりません。

末尾スラッシュに特定の意味をもたせてはなりません。リソースパスは 末尾にスラッシュがあろうがなかろうが、同じ結果を返さなければなりません。

もしソートやページネーション、フィルタ関数または他のアクションをサポートしたクエリを提供することになったら、 次に示す標準の命名規約にしたがってください。

RESTはリソースにまつわるものが全てです。したがって、Webサービスとドメインエンティティがどうやり取りするか、標準のHTTPメソッドを使ってAPIをどうモデル化するか、が関心事となります。 例えば、記事の編集するアプリケーションで、同時に1人のユーザしか編集できないように明示的にロックをしたいとします。「ロックする」というアクションの代わりに、「記事のロック」をPUTまたはPOSTで生成するようにします。

リクエスト:

これは記事のロックを閲覧したり、フィルタリングしたりするサービスがすでに存在していると、追加のメリットとなります。

APIはプロセスを表現したすべてのリソースを含んだ、完全な業務プロセスを含めるべきです。 そうすることによって、クライアントが業務プロセスを理解し、業務プロセスの一貫した設計を推進し、ドキュメントと実装の観点から相乗効果が得られるようになり、API間の暗黙的で見えにくい依存関係を消すことができます。

おまけに、業務ロジックをクライアントサイドにシフトしてしまう「データベースの薄いラッパーAPI」を避ける効果もあります。

リソースはすべてのクライアントのユースケースの90%をカバーするようにしよう、というのが経験則としてあります。 有用な リソースは情報を必要なだけ多く含むと同時に、できるだけ小さくあるべきです。 残りの10%をサポートするよい方法は、クライアントがその必要性に応じてフィルタリングしたりembeddingできるようにすることです。

APIはリソースを記述します。HTTPメソッドの中にのみ、振る舞いが現れます。 したがって、URLは名詞だけを使うようにしてください。 振る舞い(動詞)を考える代わりに、郵便ポストにメッセージを投函することを考えるようにします。 例えば、URLに キャンセル という動詞をもたせる代わりに、「注文をキャンセルする」というメッセージを、 サーバの キャンセル 郵便受けに届ける、と考えるのです。

APIリソースはアプリケーションのドメインモデルの要素を表現するものです。 リソース名にドメイン固有の命名法を使うことは、開発者がリソースのもつ機能や基本的な意味を理解するのに役立ちますし、 API定義の以外にドキュメントをたくさん書かなきゃいけない必要性を軽減できます。 例えば「sales-order-items」は単に「order-items」とするよりも、その対象をはっきりと指し示しているのでより良いものといえます。 同様に「items」とするのは、一般的過ぎます。

URLにおけるリソースIDのエンコードを単純にするため、それらにはアルファベット、数字、アンダースコア、マイナス、コロンとピリオドのみのASCII文字列で構成します。

いくつかのAPIリソースは、サブリソースを含んだり参照したりするかもしれません。 トップレベルのリソースではないEmbeddedサブリソースは、より高次のリソースの一部であり、 そのスコープの外からは使われないものです。 サブリソースはパスセグメントに含まれた名前と識別子によって参照されます。

使い勝手を向上させるため、パスセグメントそれぞれがリソースやリソースの集合を正しく指すような、 直感的に理解できるURLを目指すべきです。 例えば /customers/12ev123bv12v/addresses/DE_100100101 はAPIのパスとしてあったとき、 /customers/12ev123bv12v/addresses , /customers/12ev123bv12v や /customers も、 原則的には妥当なパスでなくてはなりません。

基本形のURL構造:

例:

IDの生成はハイトラフィックでリアルタイム性の要求されるようなユースケースでは、 スケールの点で問題を引き起こすことがあります。 UUIDは分散非協調な方法で競合することなく、かつ他にサーバ通信の必要もなく生成可能なので、この問題の解となりえます。

しかし、UUIDにはいくつかのデメリットがあります。

UUIDはID生成がボトルネックとなるようなときまで避けるべきです。 代わりに、例えばIDリソースへのPOSTしてID生成してから、エンティティリソースへの冪等なPUTをするようにできます。 特にカーディナリティが低いけれども、いろんな機能で利用されるbrand-idやattribute-idのようなものに、 マスタデータや設定データの主キーとしてUUIDを使うことは控えましょう。

また連番識別子は、発注量のような業務上の機密情報を、権限をもたない顧客にまで 漏らしてしまう可能性があることに気をつけてください。

どんな場合も、IDには数値型よりも文字列型を常に使うべきです。 これはIDの体系が進化していくときに、自由度が高くなるからです。 したがって、UUIDはformatプロパティで修飾してはいけません。

ヒント: よくランダムUUIDが使われます。 RFC 4122 のUUID バージョン4をみてください。 UUID バージョン1は、タイムスタンプを元に作るけれども、生成順にソートはできない仕様です。 ULID (Universally Unique Lexicographically Sortable Identifier) はこの欠点をなくすように作られています。 生成時間でソートするページネーションのユースケースなどでは、UUIDの代わりにULIDが使えるでしょう。

もしサブリソースがその親リソースにアクセス可能で、親リソースなしでは存在しえないものであったら、 ネストURL構造を検討しましょう。

例えば、以下のようなものです。

しかし、リソースがそのユニークなIDによって直接アクセスされうるとしたら、 APIはトップレベルのリソースとして用意するべきです。

例えばカスタマは複数の販売注文をもちますが、販売注文にはユニークなIDがふってあって、 いくつかのサービスからは直接注文にアクセスするかもしれない場合です。

そのようなケースでは以下のようにします。

サービスの開発・メンテナンスを続けていくためには、「機能分割」や「関心の分離」の設計原則にしたがい、 同一のAPI定義に異なる業務機能群を混ぜ込まないようにするべきです。 実際にAPIをつうじて機能提供されるリソースの種類は、その数に上限をもうけたほうがよいでしょう。

リソースの型はコレクションのような関連するリソース、そのメンバ、サブリソースの集合として定義されます。 例えば、下記のリソース群はカスタマ、住所、カスタマの住所の3つのリソース型として数えられます。

注意:

この定義にしたがうと、経験的にリソースのタイプは4〜8より多くなることはないと思います。 より多くのリソースを必要とする複雑な業務ドメインでは例外があるかもしれませんが、 その際はAPIを分類することによって、サブドメインに分割できないかをまず検討するべきです。

そうはいっても1つのAPIは、利用者が業務フローを理解できるように完全な業務プロセスをモデル化し、 必要なリソースすべてを揃えたものであるべきなのは、お忘れなく。

(ルートからのURLパスをもつ)メインリソースと(非ルートのURLで表される)サブリソースが 存在します。対象のリソースのライフサイクルが、メインリソースと(疎に)結びついていれば、 サブリソースを使います。つまりメインリソースは、サブリソースエンティティの コレクションリソースの役割を担います。 サブリソースの(ネストした)レベルは3以下にすべきです。 それ以上になるとAPIの複雑性は増し、URLパスも長くなりすぎてしまうからです。 (ふつうのWebブラウザは2000文字以上のURLをサポートしないことを忘れずに)

以下に示すように、標準のHTTPメソッドの意味に沿うようにしましょう。

RESTfulサービスにおけるリクエストメソッドは…​

注意: 上記の定義で_意図された(副)作用_ により、サーバはロギング、アカウンティング、プリフェッチなどの追加の状態変更する振る舞いを提供します。ただし、これらの実際の作用と状態変更が、その操作によって意図されたものであってはなりません。

メソッド実装は、 RFC 7231 にしたがい、次の基本的な性質を満たさなければなりません。

注意: MUST キャッシュ可能な GET, HEAD, POST エンドポイントをドキュメント化する

多くの場合で、例えば同じリソースが並行して作成または変更されたり、複数回にわたって変更されたりする可能性がある場合など、クライアントが競合を明らかにし、リソースの重複(いわゆるゾンビリソース)や、更新内容の消失を防ぐために、POSTとPATCHの冪等性を設計することが役立ちます。冪等 APIエンドポイントを設計するには、次の3つのパターンのいずれかを適用することを検討する必要があります。

注意: 条件付きキー と セカンダリキー は、同時リクエストを扱うのに注力していて、 冪等キー は上で定義された冪等性よりも より強い 要求となる正確に同じレスポンスを返すということに注力しています。したがって他の2つと組み合わせることができます。

あなたのユースケースにどのパターンが適しているかを決めるために、各パターンの主要な判断軸を示した以下の表をよく見てください。

注意: PATCHに適用可能なパターンは、同じプロパティを提供するPUTおよびDELETEに同じ方法で適用できます。

安全なリトライをサポートすることを主目的するならば、条件付きキーとセカンダリキー パターンを冪等キーパターンの前に適用します。

生成時のPOST 冪等を設計するための最も重要なパターンは、重複リソースの問題(いわゆるゾンビリソース)を無くすために、リクエストボディにリソース固有の セカンダリキー を導入します。

セカンダリキーは、リソースに 代替キー または(もし複数のプロパティからなるのであれば) 複合キー として永続的に保存され、サーバサイドで実行される一意制約によって上記問題からガードします。 最良かつ自然に存在する候補は、新しく生成されたリソースと 1対1 の関連をもつ別のリソース(親プロセス識別子など)を指す 一意の外部キー です。

セカンダリーキーの例として良い例は、注文リソースにおけるショッピングカートIDです。

注意: Idempotency-Key無しにセカンダリキーパターンを使うときは、全ての一連のリトライはコード409(conflict)で失敗すべきです。リソースが明確に定義された振る舞いを実装する元のリソースであるという確信がないのであれば、200を使うのは避けたほうがよいでしょう。コンテンツなしで204を使うことも、同様に適切に定義された選択肢です。

カンマで区切られた値のリストか、パラメータを複数回繰り返すかのどちらかで、ヘッダとクエリパラメータで値の集合を渡すことができます。

Open APIでは一度に両方のスキーマをサポートできないので、API仕様ではどちらかを明示的に定義しなければなりません。

コレクションフォーマットを選択する際には、ツールのサポート、特殊文字のエスケープ、URLの最大長を超えないかに注意してください。

クエリパラメータを使って、大部分のAPIのリソース固有のクエリ言語を記述することを推奨します。これはクエリパラメータがHTTPネイティブであり、拡張が容易で、HTTPクライアントおよびWebフレームワークで優れた実装サポートがあるためです。

クエリパラメータは、次の観点をもつべきです。

クエリパラメータがどのように命名され、どのように使われるかは、個々のAPI設計者次第です。次の例を参考にしてください。

私たちは、特定の名前を支持したり反対したりはしません。最終的にAPIはそのドメインに最も適した用語を自由に選択すべきだからです。

<236, query parameters>>に基づく最小のクエリ言語は、単一の方法のみで結合される少ないフィルタ(例えば and セマンティクス) を使う単純なユースケースに適しています。一般的にもシンプルなクエリ言語の方が、複雑なものよりも好まれます。

APIによってはより複雑なクエリ言語が必要なこともあります。代表的な例は検索(ファセット検索を含む)APIと、製品カタログAPIです。

これらのAPIは他のAPIと以下の点で異なります。

特定の複雑なクエリ言語に合うAPIは、ネストしたJSONデータ構造を使い、Open APIを使って直接定義するのがよいでしょう。これには以下のメリットがあります。

JSON-specific rules と、おそらくきっとGET-with-bodyパターンを使うことになるだろう。

あるコレクションリソースやクエリが、持っている要素全てではなく、現在のクライアントにアクセスが許可されたものだけを返すことがあります。

次の場合に、暗黙的フィルタリングされます。

そのような場合、暗黙的なフィルタリングはAPI仕様として(そのdescriptionに)書かれなくてはなりません。

暗黙的なフィルタリングするときは、caching considerations も考えよう。

例:

会社 Foo の従業員が当社の企業間サービスの一つにGETアクセスする場合、法律上の理由から、会社が所有または契約管理していない他のビジネスパートナーを法事してはなりません。私たちが、会社 Bar と一緒にビジネスしていることは決してバレてはなりません。

Foo で動作するコンシューマからはレスポンスは次のように見える。

Bar で動作するコンシューマからはレスポンスは次のように見える。

API仕様はこのように何を特定するかを示すべきです。

APIは機能、業務の観点で定義され、実装の観点からは切り離され抽象化しなければなりません。 成功と失敗のレスポンスは、APIが正しく使われるために必要不可欠な部分です。

だからAPI仕様においては、すべての成功とサービス固有のエラーレスポンスを定義しなければなりません。 両者ともインタフェース定義の一部であり、サービスクライアントが標準だけでなく例外も、 正しく扱うための重要な情報を提供するものです。

ヒント: たいていの場合、すべての技術的なエラー、特にサービスプロバイダに制御されないようなものを、 ドキュメント化するのは役に立ちません。 レスポンスコードがアプリケーション固有の機能の意味を伝えないか、または 追加の説明を必要とするような標準でない使われ方をする限りは、 複数のエラーレスポンス仕様は、次のパターンを用いて組み合わせることができます。(MUST 永続的で不変であるリモート参照のみを使うも参照)

API設計者は関連するオンラインAPIドキュメントの一部として、 トラブルシューティングボード について考えなければなりません。 API固有のエラーについての情報とハンドリングの指針を提供し、API仕様からリンクを通じて参照されるものにもなります。 これはサービスのサポート業務を減らし、サービス利用者、提供者双方の業績に貢献します。

標準のHTTPステータスコードのみを使い、その意味に沿うように一貫性をもった設計をしなければなりません。 どうかHTTPステータスコードを新たに発明しないようにしてください。

RFCの標準では ~60 の異なるHTTPステータスコードと同時にその意味も定義されていてます。 (主に RFC7231 と RFC-6585) — そして draft legally-restricted-status のように新しいものもあります。 すべてのエラーコードは Wikipedia か https://httpstatuses.com/ で '非公式なコード'(NginxのようなWebサーバで使われるもの)を含んだものを 見ることができます。

以下によく共通で使う(RFC標準と整合性ある)HTTPステータスコードを、理解の助けになるよう一覧にしました。 ここに載ってないHTTPステータスコードを使っても良いですが、 その場合、API定義に明示しなくてはなりません。

重要: ここに定義された意味でコードを使う限りは、そうする必要はありません。 一貫性のない定義をしてしまうリスクは低いし、常識をドキュメントに書きすぎると可読性が下がるからです。 HTTPステータスコードがリストにない、または使うには追加の情報が必要とされるときだけ、API仕様にレスポンスのHTTPステータスコードの詳細を明記しましょう。

処理結果やエラー状況を返すとき、もっとも適したHTTPステータスコードを使わねばなりません。

APIには性能上の理由から、つまり通信と処理を効率化する目的で、POSTを使った バッチ または バルク リクエストを 提供する必要があります。 この場合、サービスはバッチまたはバルクリクエストの各パートに対応した複数のレスポンスコードを 通知する必要があるかもしれません。 HTTPはバッチ/バルクリクエストとレスポンスの扱いに関して、指針を示していないので、 私たちは次のようなアプローチを定義します。

すべてのパートで処理が 失敗 したり、各パートが 非同期に 実行される 場合においても このルールが適用されます! 一貫した方法で、クライアントがバッチ/バルクリクエストの個々の結果を精査しなくてはならない ことを意図しています。

注意: バッチ とは独立した処理を起動するリクエストの集合であり、 バルク とは1つのリクエストで独立した作成または更新用リソースの集合である、 と定義しています。処理結果のレスポンスに関していえば、この違いはあまり重要では ありません。

クライアントのリクエストレートを管理したいAPIは、もしクライアントがリクエストレートを超過したら、429 (Too Many Requests)レスポンスコードを使わなければなりません (RFC 6585参照)。 そのようなレスポンスは、クライアントにそのような追加の情報を知らせるために、 ヘッダをセットしなくてはなりません。その手段は次の2つがあります。

'X-RateLimit' ヘッダには、以下のようなものがあります。

両方のアプローチを認めている理由は、APIごとに異なるニーズが存在するからです。 Retry-After は一般的な負荷やリクエストのスロットリングに関しては十分なものですが、 テナントや指定取引先のような対象毎にスロットを用意する場合においては適していません。 これによって、リソースオーナーはクライアントのリクエストに関して、管理しなくてはならない状態の数を最小化できるようになります。 一方、'X-RateLimit’ヘッダは、クライアントが既存の取引先やテナント毎にシナリオを用意するのに適しています。 'X-RateLimit' ヘッダは一般的に429のときだけでなく、すべてのリクエストに対して付与されます。 これはそのAPIを実装したサービス与えられたウィンドウで、各スロット対象毎にリクエストの数を 追跡できる能力があることを暗に示しています。

RFC 7807 でProblem JSONオブジェクトと、 application/problem+json メディアタイプが定義されています。 処理中に発生したどんな問題も(適切なステータスコードとともに)これを使い、 クライアントサイドのエラー(4xx)か、サーバサイドのエラー(5xx)かに関わらず、 ステータスコードよりも詳細な情報を返すべきです。

Problem JSONオブジェクトのOpenAPIスキーマ定義は、 GitHub上 にあります。

これを使って以下のように定義できます。

もしAPIが追加のエラー詳細情報を返す必要があれば、 Problem JSONの拡張としてカスタムの型を定義することもできます。

ヒント (後方互換性のために): このガイドラインの以前のバージョンでは(RFC 7807 が 公開される前だったので)、 application/x.problem+json のメディアタイプを返すようにしていました。 この変更前に定義されたAPIサーバは、 クライアントが送る`Accept`ヘッダとエラーレスポンスの`Content-Type`ヘッダの 対応に注意しなければなりません。 またそのようなAPIのクライアントは、両方のメディアタイプを受け付け可能でなければなりません。

スタックトレースには、APIの一部だけでなく、クライアントが依存すべきでない実装の詳細が含まれます。 さらにはスタックトレースは、パートナーやサードパーティが受け取ってはならない機微な情報を漏らしてしまう 可能性があるし、攻撃者に脆弱性についてのヒントを与えることにもなりかねません。

APIはクライアントの必要性に応じて、帯域幅を減らすための仕組みをサポートすべきです。 パブリックなインターネットやテレコミュニケーションネットワークのように、 大きなペイロードをもち高トラフィックなシナリオで使われる(かもしれない)APIに有効です。 低帯域での通信を余儀なくされるモバイルWebアプリのクライアントが使うAPIは、その典型例です。 (Zalandoは’モバイルファースト’な企業なので、この点は心にとどめておきましょう)

共通のテクニックは、

それぞれの詳細は以下に示します。

圧縮時間がボトルネックになるほど多くのリクエストを捌かなければならないなど、 特別な理由がない限りは、APIレスポンスのペイロードをgzipで圧縮しましょう。 そうすることでネットワークの転送も速くなるし、フロントエンドの応答性も向上します。

gzip圧縮がサーバペイロードのデフォルトの選択肢ではありますが、サーバは 圧縮しないペイロードもサポートするべきです。クライアントはAccept-Encodingリクエストヘッダを 通じてそれをコントロールできます。 RFC-7231 Section 5.3.4 も参照してください。 サーバもまたContent-Encodingヘッダを通じて、gzip圧縮が使われていることを明示すべきです。

ユースケースとペイロードサイズに応じて、返却するエンティティのフィールドの フィルタリングをサポートすることによって、必要とするネットワーク帯域を大いに減らこすとができるでしょう。 フィールドクエリパラメータを付けることで、クライアントは欲しいデータに応じて、 フィールドのサブセットを決めることができます。 例は Google AppEngine API’s partial responseをみてください。

関連するリソースを組み込むこと( リソース展開 として知られる)は、リクエスト数を減らすためには すごくよい手段です。 クライアントが前もって必要な関連リソースを知っている場合は、クライアントからサーバに、 データをEagarにプリフェッチできるよう指示します。 これはサーバで最適化されるのか(例えば、データベースのJOIN)、 一般的な手段(例えば透過的にリソースを差し込むHTTPプロキシ)で実現されるのかは、 実装次第です。

命名に関しては MUST クエリストリングの規約を使う を参照ください。例えば埋め込みリソース展開には "embed" を使います。 埋め込みクエリには、前述のフィルタリングと同様の BNF 文法を使うようにしてください。

サブリソースの埋め込みは、例えばある注文がそのサブリソース (/order/{orderId}/items) として注文品目をもつような場合には、以下のようにみえます。

キャッシュは多くのことを考慮しなければなりません。例えば、一般的なレスポンス情報のキャッシュ可能性や、SSLを使ったエンドポイントを保護するガイドライン、リソースの更新とキャッシュ無効化のルール、複数のAPI利用者の存在などがあります。結果として、キャッシュは最良でも複雑(一貫性の観点などから)、最悪の場合は逆に非効率的なものになります。

頻繁に使用され、そのためにレート制限されたマスタデータサービス、すなわち、作成後にほとんどあるいは全く更新されないデータなど、サービスがそれ自体を保護することをサポートしない限り、クライアントサイドでの、また透過的なWebキャッシュを使うことは避けるべきです。

デフォルトでは、API提供者と利用者は常にCache-ControlヘッダをCache-Control: no-storeにセットすべきであり、もしCache-Controlが設定されていなければ、同じくCache-Control: no-storeがセットされたものとして扱うべきです。

注意: このデフォルト設定をドキュメント化する必要はありません。ただし、フレームワークがデフォルトでこのヘッダの値を付加していることを確認するか、あるいは手動で(例えば下記のようなSping Securityのベストプラクティスを使って) これを確認してください。このデフォルトから外れた設定は、十分なドキュメント化が必要です。

もしサービスが本当にキャッシュのサポートを必要とするなら、以下のルールにしたがってください。

ヒント: キャッシュを適切にサポートするために、失敗したHEADリクエストまたはGETリクエストでは、304ではなくIf-None-Match: <entity-tag>を指定したコンテンツなしの412を返す必要があります。

ヒント: ETagソースにはMAY If-Match/If-None-MatchヘッダともにEtagのサポートを検討しようを参照してください。

Cache-Controlのためのデフォルト設定は、標準のOAuth認証を持つエンドポイントに対する private ディレクティブと、クライアントが古いキャッシュエントリを使わないようにするための must-revalidate ディレクティブが含まれている必要があります。 最後に max-age ディレクティブは、マスタデータの変更率とクライアントの一貫性を保つための 要件に応じて、数秒( max-age=60 )から数時間( max=age86400 )の間の値に設定する必要があります。

Varyのデフォルト設定を正しく決めるのはもっと難しいことです。 APIエンドポイントに大きく依存します。例えば、圧縮をサポートするかどうか、 異なるメディアタイプを受け付けるかどうか、他のリクエスト固有のヘッダを 必要とするかどうか、など。正しいキャッシュをサポートするには、この値を 注意深く選択してください。出発点となるデフォルト値は、おそらく以下のものでしょう。

いずれにせよ、これはクライアントに一般的なHTTPレイヤクライアントとプロキシキャッシュを クライアントが使おうとするときのみ、これが関係してきます。

注意: HTTPレベルでの一般的なクライアントとプロキシキャッシュは、設定が難しいです。 それゆえに、(おそらく分散)キャッシュを、アプリケーションのサービス(またはゲートウェイ)レイヤ に直接用意することを強く推奨します。Varyヘッダの解釈から解放され、Cache-Controlと ETagヘッダの理解も非常に単純になります。さらにはキャッシュパフォーマンスやオーバーヘッドに ついても非常に効率的にもなるし、高度なキャッシュ更新とウォームアップのパターン.もサポートできるようになります。

いずれにせよ、どんなクライアントキャッシュやプロキシキャッシュを導入する前には、 RFC 7234 を注意深く読んでください。

リストデータへのアクセスは、クライアントサイドの一括処理と繰り返し操作のために、ページネーションをサポートしなければなりません。これは数百エントリ以上の(になる可能性のある)リストすべてにあてはまります。

2つのページネーションのテクニックがあります。

ページネーションの技術的概念は、問題がユーザエクスペリエンスと結びついていることも考慮しなければなりません。 この 記事 で述べられているとおり、 特定のページへのジャンプは、「前へ」「次へ」のページリンク(SHOULD 適用可能なところではページネーションリンクを使う参照)よりもあまり使われることはありません。 それがオフセットベースのページネーションよりも、カーソルベースのページネーションを指向したい理由です。

注意: ページネーションの一貫したルックアンドフィールを提供するため、MUST クエリストリングの規約を使うで定義された共通のクエリパラメータ名を使わなければなりません。

カーソルベースのページネーションは、オフセットベースのページネーションと比較すると、 いい感じでより効率的です。 データ量が多くなってきた時やNoSQLデータベースのストレージでは特に顕著です。

カーソルベースのページネーションを選択する前に、次のトレードオフを検討しておきましょう。

ページネーションのために使われるcursorは、ページへのOpaqueポインタで、クライアントが 検査 したり 構築 したりしてはならない。通常は安全にコレクションを再作成できるように、ページの位置、すなわち、最初または最後のページ要素の識別子、ページネーションの方向、適用されたクエリフィルタを(暗号化)エンコードしたものです。cursorは次のように定義されます。

カーソルベースのページネーションのためのページ情報は、cursorの集合で構成する必要があります。nextに加えて、prev,first,last,selfを次のようにサポートすることもあります。(リンク関連フィールド参照)

注意: cursor集合のサポートはSHOULD 適用可能なところではページネーションリンクを使うが好まれて、削除されるかもしれません。

さらには以下の文書もあります:

クライアント設計を単純にするために、APIはコレクションのページネーションに適用できるときはいつでもsimplified hypertext controlsをサポートするべきです。nextに加えて、prev, first, last, selfのサポートを含むこともあります。(詳細はリンク関連フィールド参照)

このページ内容はitemsを通じて送信さる一方、queryオブジェクトは次のように適用されたクエリフィルタも含むかもしれません。

注意: 例えばGET With Bodyが必要なときのような、複雑な検索リクエストでは、cursorはすべてのクエリフィルタをエンコードできないかもしれない。この場合、ページ位置とcursorの方向だけをエンコードし、ボディでクエリフィルタを送るのがベストプラクティスでしょう。レスポンスも同様です。ページネーションの順序を守るため、この場合、cursorが適用されたすべてのクエリフィルタのハッシュを含ませ、使う前に検証するのがおすすめです。

注目: 必要性がない限り、トータル数を与えるのを避けるべきです。多くの場合、全件カウントをサポートすると、システムと性能に多大な影響が出ます。特にデータセットが増大し、リクエストが複雑になった場合は、フィルタによってフルスキャンが実行されます。これはAPIに関連した実装の詳細ですが、サービスの生存よりも、カウント機能が重要なのかよく考えましょう。

私たちは REST 成熟度レベル2 のイケてる実装を目指します。 そうすることでHTTP動詞とステータスコードをフル活用した、リソース指向APIを構築できるようになるからです。 これらのガイドラインを通じて、これは多くのルールによって表現されています。

これはHATEOASではありませんが、以下に示すルールで記述されるように、 APIに正しいリンク関連を設計することにとらわれるべきではありません。

私たちは基本的には、 REST 成熟レベル3 を実装すことはおすすめしません。 HATEOASは、クライアントとサーバのREST APIを通じたやりとりしたり、 私たちのeコマースのSaaSプラットフォームの一部として複雑な業務機能を提供したりする、 私たちのSOA文脈においては、価値のない複雑さをAPIにもたらします。

私たち主な関心は、HATEOASのもたらす利点にあります。 (詳細な議論は RESTistential Crisis over Hypermedia APIs や Why I Hate HATEOAS 、を参照ください)

しかし、私たちはHATEOASを禁止するわけではありません。 その制限を理解し、複雑さを代償としてもより価値のある利用シーンがあるのであれば、HATEOASを使ってもかまいません。

他のリソースへのリンクは、絶対URIでなくてはなりません。

動機: 相対URI (相対URLが絶対パスを使おうが相対パスを使おうが) の形式を露出させると、 クライアントサイドでは複雑性の混入を避けることができません。 埋め込みサブリソースのような機能を使うときは、絶対URIが与えられないとすれば、 ベースURIを明確にする必要があります。 絶対URIを使わないことの利点は、ペイロードサイズを小さくできること程度ですが、 それならば GZip圧縮を使った方がよいでしょう。

他のリソースへのリンクを埋め込むとき、共通のハイパーテキストコントロールオブジェクトを 使わなくてはなりません。ハイパーテキストコントロールオブジェクトには、少なくとも1つの属性が含まれます。

どんなハイパーテキストコントロールを含むAPIにおいても、 属性名 href はハイパーテキストコントロールの範囲内での使用用途で予約語となります。

ハイパーテキストコントロールのスキーマは、以下のモデルから導き出されます。

HttpLink のようなオブジェクトをもつ属性の名前は、リンクとリンク先のリソースを含む オブジェクトとの関係を明記します。 実装は IANA Link Relation Registry から適切なものを選んで、その名前を使うべきです。 このガイドでは属性名にはスネークケースが使われていますが、 IANAのリンクリレーション名は、ハイフンケース表記が使われています。IANA名のハイフンは、 アンダースコアに変換しなければなりません。 (例えば、IANAリンクリレーションタイプ version-history は属性 version_history になります)

特定のリンクオフジェクトは、リンクに加えて、 リンク先のリソースに関する追加情報や、リンク元のリソースとリンク先のリソースの関係など、 その他の属性を含ませることができます。

例えば、"Person" リソースを提供するサービスは、他の誰かと結婚していることを、 その結婚相手の (id, name) だけでなく、いつから配偶者関係にあるかを示す (since) などを含んだハイパーテキストコントロールでモデル化します。

ハイパーテキストコントロールは、JSONモデルの範囲ではどこでも使えます。 この仕様においては HAL が 使用可能ですが、APIの理解しやすさや使いやすさがもたらす価値よりも、 メタデータとデータの構造的な分離の有害さが上回るため、私たちはHALはおすすめいないし使いません。

コレクション内でのページネーションや自己参照のためのハイパーテキストコントロールは、 拡張共通ハイパーテキストコントロールを使うよりも、 リンクリレーション で定義されている (next prev first, last, self) 組合せたシンプルなURIを使うべきです。

[simple-hypertext-control-fields]とSHOULD 適用可能なところではページネーションリンクを使うに、より例と詳細な情報があります。

柔軟性と精度のため、一般的ではないリンクヘッダ構文を使って、リンクを付加するのではなく、JSONペイロードに直接埋め込まれるリンクを好みます。結果として、 RFC-8288で定義される Link ヘッダ を使うことは禁止されます。

構造化データを転送するためにJSONエンコードされたボディのペイロードを使いましょう。JSONペイロードは RFC 7159 にしたがわなければなりません。トップレベルの構造としては、(可能であれば)将来拡張可能なように、JSONオブジェクトを使います。これはまた、Arrayを想定しているであろうコレクションリソースにも適用します。MUST 常にトップレベルのデータ構造としてJSONオブジェクトを返す参照。

それに加えて、JSONペイロードは部分的に、 RFC 7493 に準拠しなければなりません。

結果としてJSONペイロードは、以下のようになります。

他のメディアタイプは次のようなケースで使われます。

代替メディアタイプを使ったバイナリーデータが一般的には好まれます。上のルールを参照。

もし代替のコンテント表現が望むものでなければ、バイナリデータは base64url エンコードされた文字列プロパティとして、JSONドキュメントに埋め込まれるべきでです。 RFC 7493 Section 4.4 参照。

以前このガイドラインでは、application/x.zalando.article+json のようなカスタムのメディアタイプを使ってもよいとしました。これは、media type versioningで必要な場合以外では、おすすめしないし避けるべきです。かわりに、標準のメディアタイプである application/json (または application/problem+json MUST Problem JSONを使う) を使いましょう。

x で始まるカスタムのメディアタイプは、JSONの標準メディアタイプと比較して何のメリットもないばかりか、自動化をより難しくしてしまいます。これはまた RFC 6838で使用を抑制されています。

JSON Schema と Open API では、いくつか有用で広く使えるプロパティフォーマットを定義しています。次の表は、Eコマース環境で特に役に立つ追加のフォーマットをいくつか含んでいます。

国、言語、通貨は次の標準コードを使いましょう。

APIで number または integer の型のプロパティを定義するときは、 クライアントが誤った精度を使って、無意識に値が変わってしまわないように、精度を定義しなければなりません。

精度はクライアントとサーバの双方で、もっとも適した言語の型に変換されなければなりません。 例えば、次の定義においてJavaでは、 Money.amount は BigDecimal に、 OrderList.page_size は int または Integer に変換されるでしょう。

以下のような共通のお金構造を使いましょう。

Moneyのグローバルスキーマを参照をincludeするとよい。

APIが閉じたデータ型として、Moneyを取り扱わなくてはならないことに注意しましょう。つまり、インスタンス階層で使わることを意味しません。次のような使い方が許されないことを意味します。

複数の場所で使われるフィールドの型があります。すべてのAPI実装にわたって一貫性を保つために、 どんなときでも適用可能な共通のフィールド名とセマンティクスを使わなければなりません。

Contentやエンティティに関するヘッダには、Content- のプレフィクスが付いています。 これらにはメッセージボディの内容に関することが書かれていて、HTTPリクエストとレスポンスの両方で使用されます。 共通的に使われるContentヘッダは次のようなものですが、その限りではありません。

このリスト を使い、Open API定義にサポートするヘッダを記述します。

Content-Location ヘッダは 任意 であり、成功した書き込み操作(PUT, POST, PATCH)や読み込み操作(GET, HEAD) で使われ、キャッシュ位置を示したり、リソースの実際の場所を受信者に通知したりします。 これによりクライアントはリソースを識別し、このヘッダの付いたレスポンスを受け取ったらローカルコピーを更新することができるのです。

Content-Locationヘッダは、次のユースケースを実現するのに使われます。

注意: Content-Locationヘッダを使用する際には、Content-Typeヘッダも正しく 設定しなければならない。例えば、以下のように。

セマンティクスやキャッシュに関して、Content-Locationを正しく使うのは 難しいので、私たちはContent-Location の使用を 推奨していません 。 たいていの場合、Content-Location特有の曖昧さや複雑さに悩まされる代わりに、 Locationヘッダを使うことで、クライアントにリソースの場所を直接知らせることで十分です。

より詳細な話が、RFC 7231 7.1.2 Location , 3.1.4.2 Content-Location にあります。

Preferヘッダは {RFC7240}[RFC 7420] で定義されており、クライアントがサーバの振る舞いをリクエストするのに使われます。多くのプリファレンスが事前定義されていて拡張も可能です。 Preferヘッダのサポートは、任意でありAPI設計の裁量次第ですが、 既存のインターネット標準と同様に、独自の"X-"ヘッダを定義して処理することをおすすめします。

PreferヘッダはAPI定義に次のように定義します。

注意: APIエンドポイントがサポートするPreferヘッダの仕様へは振る舞いだけをコピーしよう。必要ならそれぞれのサポートされるユースケースで異なるPreferヘッダを明記しよう。

サポートするAPIはPreference-Appliedヘッダを返してもよい。これは RFC 7240 で定義され、プリファレンスが適用されたかどうかを指し示す。

リソースが作成、更新されるときは、コンフリクトの発生を検知し、'更新データのロスト’や’重複して作成される’問題を防ぐ必要があります。 [RFC-7232]{RFC 7232 "HTTP: Conditional Requests"} にしたがい、ETagヘッダをIf-MatchまたはIf-None-Matchの条件ヘッダとともに使うことで、それが出来るようになります。 ETag: <entity-tag> ヘッダの内容は、(a) レスポンスボディのハッシュ値か、 (b) エンティティの最終更新日時フィールドのハッシュ値、(c) エンティティのバージョンの番号または識別子の何れかにします。

PUT, POST, PATCHの同時更新操作でコンフリクトが発生したことを検出するために、サーバは If-Match: <entity-tag> ヘッダがあれば、更新エンティティのバージョンが、リクエストの{entity-tag>}と一致しているかをチェックしなければなりません。 もし一致するエンティティがなければ、412 - precondition failed のステータスコードを返すようにします。

他のユースケース、リソース生成時にコンフリクトを検出する方法と同様に、 If-None-Match: * が使えます。 もしエンティティにマッチするものがあれば、既に同じリソースが作成されていることを 示すので、412 - precondition failed のステータスコードを返します。

ETag, If-Match, If-None-Matchヘッダは、API定義においては次のように定義されます。

別のアプローチについての議論は、RESTful APIにおける楽観ロック セクションも参照ください。

リソースを生成したり更新したりするとき、タイムアウトやネットワーク障害のためにリトライするケースで、重複実行を避けるため同じレスポンを返す強い冪等性が役に立ったり、必要になったりします。一般的にこれはクライアント固有の 一意のリクエストキー をリソースの一部ではなく、Idempotency-Keyヘッダを通じて送信することによって実現されます。

一意のリクエストキー は、一時的(例えば24時間くらい)に保存され、成功したか失敗したかによらずレスポンスと(これはオプションですが)最初のリクエストのハッシュを一緒に格納します。サービスは、冪等動作を保証するために、リクエストをリトライする代わりに、キーキャッシュ内の_ 一意のリクエストキー_ を検索し、キーキャッシュからレスポンスを返すことができます。オプションとして、レスポンスを返す前にリクエストのハッシュを使って整合性をチェックできます。キーがキーストアにない場合、リクエストは通常どおり実行され、レスポンスはキーキャッシュに格納されます。

これにより、クライアントは同じレスポンスを複数回受信しながら、タイムアウトやネットワーク障害などの後に安全にリクエストをリトライできます。 注意: このコンテキストでのリクエストのリトライは、全く同じリクエストを送信する必要があります。つまり、結果を変更するようなリクエストの更新は禁止されています。キーキャッシュ内のリクエストハッシュは、この誤った使い方から保護することができます。このようなリクエストは、ステータスコード400を使用して拒否することをお勧めします。

重要: 信頼性の高い冪等実行セマンティクスを付与するには、分散システムにおける障害、タイムアウト、同時リクエストの潜在的なすべての落とし穴を考慮して、リソースとキーキャッシュをハードトランザクションセマンティクスで更新する必要があります。これは、ローカルコンテキストを超える正しい実装を非常に難しくします。

Idempotency-Key ヘッダーは次のように定義する必要がありますが、有効期限は自由に選択できます。

ヒント: キーキャッシュはリクエストログとして意図されていません。したがって、その生存期間は制限すべきだし、そうしないとデータリソースのサイズを簡単に超えてしまうことになります。

注意: Idempotency-Key ヘッダはこのセクションの他のヘッダと異なりRFCで標準化されていません。 Stripe APIでの使われ方だけを参考にしました。独自ヘッダのセクションの規約とは合いませんが、ヘッダの名前と意味を変えたくはなく、他の共通ヘッダと同じようにこれを扱うことを決めました。

一般的なルールとして、独自HTTPヘッダは避けるべきというのがあります。エンドトゥエンドで複数のサービスを通して渡される必要があるとそれが効いてきます。 APIの一部分だけではなく、それに続くやり取りに必要とされる文脈情報も与えるようなところで独自ヘッダを用いるのは、妥当なユースケースです。

概念的な観点から、API操作の意味と意図はURLパスとクエリパラメータ、メソッド、コンテントで常に 表現されているべきです。ヘッダはフロー制御やコンテントネゴシエーション、認証のようなプロトコル に近い機能を実装するのに使われます。 ですので、ヘッダは一般的な文脈情報のために予約されているのです。 (RFC-7231)

X- ヘッダは、最初は非標準のパラメータのために予約されていましたが、 X- ヘッダを使用は、 RFC 6648 で 廃止予定になりました。 これらのヘッダを使う整合性の取れた方法がないので、ガイドラインにしたがう APIの利用側・提供側の間でのやりとりの規定は複雑化します。 そのため、ガイドラインではどの X- ヘッダを使用するか、どう使われるかを制限しています。

RFC6648 の中で、 企業固有のヘッダの名前には、組織の名前を含むべきだ、という見解を Internet Engineering Task Force は示しています。 私たちは後方互換の目的で、 X- 始まりのヘッダを使い続けています。

次の独自ヘッダは、このガイドラインで使用法が規定されたものです。 HTTPヘッダフィールド名は、大文字・小文字を区別しないことをお忘れなく。

例外: このガイドラインの唯一の例外は、 MUST レート制限のためのヘッダと429コードを使う の定義として使われる hop-by-hopの X-RateLimit- ヘッダです。

すべてのZalandoの独自ヘッダは、End-to-Endのヘッダです。 ^[2]

上で定義したすべてのヘッダが、サービスの呼び出しチェーンで伝搬されなければなりません。 ヘッダの名前と値は書き換えてはなりません。

例えば、X-Device-Type のようなカスタムヘッダの値は、 デバイス種別の情報を使われ、クエリ結果に直接影響を与えることがあります。またリコメンド結果にも及ぶことがあります。さらにカスタムヘッダの値が、クエリ結果に間接的に影響することもあります。（デバイスタイプの情報がリコメンド結果に間接的に影響するなど）

時々、独自ヘッダの値は、後続のリクエストにおいてエンティティの一部として使われることがあります。 そのような場合は、冗長かもしれませんが、独自ヘッダを後続リクエストのヘッダとしても付けて送らなければなりません。

Flow-ID はサービスのAPIやイベントを通じて渡される汎用のパラメータで、ログファイルやトレースに書かれる。 その結果 Flow-ID を使うと、システム内のコールフローを追うのが簡単になり、特定の呼び出しによって開始されるサービスのアクティビティの関係性が明らかになります。これは運用上のトラブルシューティングやログ分析に非常に役に立ちます。 Flow-ID の主な用途は、当社のSaaSファッションコマースのサービス呼び出しと内部のプロセスフロー(API経由で同期的に実行されたものだけでなく、送出されたイベントによって非同期に実行されるものも)を追跡することです。

すべてのサービスアプリケーションは、外に向けたAPIのOpen APIの仕様を公開しなければなりません。 内部API (つまり APIオーディエンス が component-internal のもの) は任意ではありますが、APIマネジメント基盤を使うメリットは大きいので、公開しておくにこしたことはありません。

APIはその OpenAPI仕様 を、プロビジョニングサービスをデプロイするのに使われる デプロイメント成果物 の中の /zalando-apis ディレクトリへコピーすることで公開されます。 ディレクトリは それぞれ1つのAPIについて書かれた 自己完結型のYAML ファイル だけを置くようにしてください。 (今となってはレガシーな) .well-nown/schema-discovery サービスエンドポイントを使ったデプロイよりも、私たちは、この成果物ベースのデプロイを優先します。レガシーな方式は、後方互換のために残してあるだけです。

背景: 動的で複雑な私たちのインフラでは、APIクライアント開発者に、動いているアプリケーションすべてのAPI仕様を、オンラインからアクセス出来るような場所を提供することが重要です。 インフラの一部として、API公開のプロセスはAPI仕様を探し出すのに使われます。

注意: APIを公開するためには、デプロイが成功していることが前提になります。

本番環境で使われるAPIのオーナーは、使っているクライアントについて情報を得るために APIサービスをモニタリングすべきです。その情報は、例えばAPI変更時にレビューをお願い しなきゃいけない相手を特定するのに役立ちます。

ヒント: クライアントを見つけるより良い方法は、OAuthトークンから取り出したclient-idのログを取ることです。

イベントはサービスのREST APIへ同じ立場であり、外界に対してのサービスインタフェースの 一部です。データを送出するサービスは、APIと同じように、イベントを設計における最重要関心事として 扱わなければなりません。 [はじめに]で示した「APIファースト」の原則が、イベントに対しても当てはまります。

イベントを送出するサービスは、他で使えるようにイベントのスキーマを作らなければなりません。 それだけでなく、レビューのためにもイベントの型定義も作りましょう。

API仕様にイベントスキーマ仕様も揃えるために、私たちはイベントスキーマの定義にも Open API仕様を使ってスキーマオブジェクトを定義します。 これは他のAPIで使われているリソースに関するデータ変更を表すイベントにとって、特に便利なものです。

Open API スキーマオブジェクト は JSON Schema Draft 4 の 拡張可能なサブセット です。 便宜上、私たちは以下にその重要な差異を示します。 詳細は Open API スキーマオブジェクト仕様 を参照ください。

Open APIスキーマオブジェクトは、いくつかのJSONスキーマキーワードが削除されているので、 イベントスキーマでもこれらは使わないようにしてください。

一方でスキーマオブジェクトは、JSONスキーマキーワードを再定義しているものもあります。

最後に、スキーマオブジェクトは、JSONスキーマのいくつかのキーワードを 拡張しています 。

Zalandoのアーキテクチャにおいて、イベントは イベント型 と呼ばれる 構造を使って登録されます。イベント型では、次のような標準の情報を宣言します。

イベント型はイベント情報を見つけるのを簡単にし、それが良く構造化されていて、 一貫性があって検証可能であることを保証するものになります。

イベント型のオーナーは、互換モードの選択に気をつけなければなりません。 モードはスキーマの進化の方法を示します。 イベント送信者が既存のイベント受信者に不用意に破壊的変更を与えずに、スキーマを 修正するのにどれだけな柔軟性があるかは、モードの範囲の設計に依存します。

互換性モードはセマンティックバージョニング (MAJOR.MINOR.PATCH) にしたがう `version`フィールドに影響します。

次の例でこの関係性を説明します。

イベント型の主要な構造は、Open APIオブジェクトとして、以下のように定義されます。

イベント型をサポートしているレジストリのようなAPIは、サポートされたカテゴリやスキーマ形式の 集合を含んだモデルを拡張しているかもしれません。 例えばNakadi APIのイベントカテゴリレジストリは、イベントのバリデーションの宣言や 強化戦略、ストリームの中でどうパーティショニングされるかのような補足情報が 記述できるようになっています。(SHOULD データ変更イベントにはハッシュパーティション戦略を使う参照)

イベントカテゴリ はイベント型の一般的な分類です。 ガイドラインは2つのカテゴリを定義します。

カテゴリは将来的に成長していくことが予想されます。

カテゴリとは、イベント送信者が準拠しなくてはならないイベントの種類(データ更新イベントなど) に関しての標準を、事前に定義した構造で記述したものです。

汎用イベントカテゴリ

汎用イベントカテゴリ は、Open API スキーマオブジェクトの定義として、 以下のような構造で表せます。

汎用イベントカテゴリに属するイベント型は、ドキュメントのトップレベルに 標準情報のための予約されている metadata フィールドを使って、 カスタムスキーマのペイロードを定義します。 (metadata の内容は、このセクションのずっと下の方に記述してあります)

注意:

カテゴリの使い方に関するガイドは MUST 業務プロセスのステップと到達点を通知するために、汎用イベントカテゴリを使う により詳細があります。

データ更新イベントカテゴリ

データ更新イベントカテゴリ は、Open API スキーマオブジェクトの定義として、 以下のような構造で表せます。

データ更新イベントカテゴリは、構造的に汎用イベントカテゴリとは異なります。 data フィールドでカスタムペイロードを定義し、 data_type にデータ変更に関する 固有の情報を定義します。 例えば次の例では、 a と b のフィールドは、 data フィールドの内側に おかれたカスタムペイロードの一部です。

データ更新イベントカテゴリの使い方の指針は、以下のガイドラインも参照ください。

汎用カテゴリもデータ更新イベントカテゴリも、 メタデータ に関しては、 共通の構造をもちます。 メタデータの構造は、Open APIスキーマオブジェクトとして以下のように表せます。

イベントの送信者と、その最終的な受信者の間で、イベントのバリデーションやイベントの metadata を充実させるような操作がなされる可能性があることに注意してください。 例えばNakadiのようなブローカは、バリデーションしたり、任意のフィールドを追加したり、 あるフィールドが与えられていなければ、デフォルト値などをセットしたりできます。 そんなシステムがどう動くかは、このガイドラインのスコープ外ですが、イベント送信者と受信者が、 それを扱わなくてはならないので、追加の情報をドキュメントに書いておくべきです。

イベントは業務プロセス/データの分析・モニタリングを含む他のサービスによって 使われることを想定しています。 したがって、サービスドメインのために定義されたリソースや業務プロセスに基づくものであるべきだし、 業務の自然なライフサイクルに即したものであるべきです (SHOULD 完全な業務プロセスをモデル化する および SHOULD 有用な リソースを定義する を参照)。

イベント型やトピックスを大量に作るのはコストがかかるので、複数のユースケースで使えるような 抽象的/汎用的なイベント型を定義するようにしましょう。そして、明確なニーズがない限りは イベント型を公開するのは避けましょう。

APIの権限スコープと同様に、近い将来イベント型の権限もOAuthトークンで渡せるようになるでしょう。 それまでは、次の注意事項にしたがうようにしてください。

イベントが業務プロセスにおけるステップを表現したものであるならば、 イベント型は汎用イベントカテゴリのものでなくてはならなりません。

単一の業務プロセスにまつわるすべてのイベントは、次のルールを遵守してください。

単一のイベント型を使い、状態フィールドで特定のステップを表現する業務業務プロセスのイベント すべてを公開するのがよいのかどうか、 各ステップを表現するために複数のイベント型を使ったほうがよいのかどうか、 現時点では何がベストプラクティスか私たちには分かりません。 与えられた業務プロセスについて、今は私たちはそれぞれの選択肢を評価し、その1つにこだわって みようと、そう考えているのです。

データの作成、更新、削除を表すイベントを送出するとき、イベント型はデータ変更イベントカテゴリ のものでなくてはなりません。

エラーが発生した場合、イベントストリームを再構成したり、 ストリームの中での位置からイベントを再現したりすることを、イベント受信者に要求することが あります。 それゆえにイベントは、部分的な発生順を再現できる方法を含んで いなければなりません 。

これは、(例えばデータベースで作成する) エンティティのバージョンやメッセージカウンタを 使って実現します。これらは厳密かつ単調に増加する値を使います。

システムタイムスタンプを使うのはあまり良い選択ではありません。分散システムにおいて 正確な時刻同期は困難だし、2つのイベントが同じマイクロ秒で発生するかもしれないし、 またシステムクロックは、時刻合わせのドリフトやうるう秒で前後する可能性もあるためです。 もしイベントの順番を表すのにシステムタイムスタンプを使えば、設計したイベント順がこれらの影響で 混乱を来さないことを注意深く保証しなければなりません。

分散環境でデータ構造によってこの問題を解消する ( CRDTs, logical clocks や vector clocks のような) 仕組みはこのガイドラインのスコープ外であることに 注意 してください。

hash パーティション戦略は、イベントが追加されるべき論理パーティションを 計算するためのインプットとして使われるフィールドを、イベント送信者は定義できます。 イベントエンティティの順序をパーティションローカルで決めれる間は、スループットを スケールできるようになります。

hash オプションは、特にデータ変更に有用です。それによって、あるエンティティに関連するすべてのイベントを、 パーティションへ一貫性をもって割り当てることができるし、そのエンティティに関する 順序付けされたイベントストリームを提供できるようになるからです。 これは各パーティションが全順序性をもつならば、パーティションをまたいだ順序が サポートするシステムでは保証されないので、パーティションをまたいで送信されたイベントは、 サーバに到着したのとは異なる順序で、イベント受信者に見える可能性があることを示しています。

hash 戦略を使うとき、ほとんどすべての場合、パーティションキーは変更されるエンティティを 表すものであり、 `eid`フィールドやタイムスタンプのようなイベント毎に付与されたり、 変更識別子だったりするものではありません。 これによって、データの変更イベントが、同じエンティティでは同じパーティションに入ることが保証され、 クライアントは効率的にイベントを受信できるようになる。

データ変更イベントが、送信者側が定義したり、ランダムに選択したりと、 独自のパーティション戦略をもつ例外的な場合があるかもしれませんが、 一般的にいって、 ハッシュ が正しい選択しです。 ここでのガイドラインは "should" ですが、"すごくイカした理由がない限りは、must" と読み替えてください。

データ変更イベントのエンティティ表現は、REST APIの表現と対応しているべきです。

あるサービスにとって最小限の構造しか持たないようにすることに価値があります。 そうすれば、サービスの利用者にとってはより少ない表現しか使わずにすむし、 サービスオーナーにとっては、保守しなくてはならないAPIが少なくてすみます。 特に、そのドメインに関連していて、実装やローカルの詳細から切り離され抽象化されたイベントのみ 公開するようにすべきです。 システム内で起こるすべての変更を反映する必要はありません。

APIリソース表現と直接関係のないデータ変更イベントを定義する意義がある場合もあります。例えば次のような場合です。

リソースがREST APIを通じて同期的に読み取りアクセスでき、イベントを通じて非同期で読み取りアクセスできると すると、同じ読み取り権限が適用されていなければならない。 私たちはデータを保護したいのあって、データのアクセス方法を保護したい訳ではないのだから。

イベント定義は、所有者をハッキリさせておかなければなりません。EventTypeの owning_application で明示します。

EventTypeのオーナーでその定義に責任をもつのは、1つの送信アプリケーションであることが 多いですが、そのオーナは同種のイベントを送信する複数のサービスの1つであってもよいです。

イベントは他のAPIデータやAPIガイドラインと整合性のとれたものでなくてはなりません。

はじめに で表したすべてが、サービス間でデータをやり取りするイベントに適用されます。 APIと同様にイベントは、私たちのシステムが何をしているのかを表現するための責務を果たし、 高品質に設計された有用なイベントが、私たちの新しく面白いプロダクトやサービス開発を支えるのです。

イベントが他の種類のデータと異なるのは、非同期のpub-subメッセージングのように、 データの伝達に使われるところにあります。だからといって、 例えば検索リクエストやページ分割されたフィードのように、REST APIを使うような ところでイベントが使えない訳ではありません。 サービスのREST APIのために作ったモデルを、イベントでもベースとすることになるでしょう。

次のガイドラインの章がイベントにも適用されます。

イベントの変更は項目追加や後方互換のある変更を基本としなければなりません。 これは 互換性 ガイドラインの「Must: 後方互換性を崩してはならない」 にしたがうものです。

イベントの文脈では、互換性の事情は複雑です。 イベントの送信者も受信者も高度に非同期化されていて、 RESTのクライアント/サーバでは適用できていた content-negotiation を用いた テクニックは使えないためです。 これは後方互換維持のためのより高いハードルを、受信者側に課すことになります。 要求に応じてバージョニングしたメディアタイプを返すということが出来ないためです。

イベントスキーマでは、受信者側から見たときに、以下のものは後方互換性があると 考えられます。

また、受信者側から見たときに、以下のものは後方互換性がないと考えられます。

イベント型のスキーマでは、スキーマの成長をサポートするため additionalProperties の使用を避けるべきです。

イベントはpub-subシステムによって中継されることが多く、共通的にログがとられたり、 後で読み込むためにストレージに保存されたりします。 特に受信者と送信者双方で使われるスキーマは、時間とともに変化していきます。 結果として、クライアント・サーバ型のAPIではあまり起こらなかった互換性と拡張性の問題が、 イベントの設計では重要かつふつうに考えなきゃならいことになってくるのです。 イベントスキーマの成長を可能にするため、ガイドラインは次の点を推奨します。

上記制約は、イベント型スキーマの将来のリビジョンで、フィールドが追加できないことを意味してはいません。 イベント型の新しいスキーマが、イベント送信前に前にまずフィールドを定義していれば、 互換性のある追加で許されたオペレーションです。 同じ順番で、受信者はAPIクライアントと同様に、スキーマのコピーに情報のないフィールドを無視しなければなりません。 すなわち、 イベント型スキーマが拡張に対して閉じていたとしても additionalProperties フィールドがないことを扱うことができないのです。

_フィールド再定義 _ の問題を避けるため、イベント送信者にイベント送信する前に、 フィールドを定義すること要求します。 これはイベント送信者が、既に送出された異なる型のイベントにフィールドを定義したり、未定義のフィールドの型を変更したりしている場合です。 どちらも、 additionalProperties を使わないことで防げます。

additionalProperties の使用についてのガイドラインは、 互換性 の章のルール MUST Open APIの定義をデフォルトで拡張に対して開かれているものとして扱う を参照ください。

イベントの eid (イベント識別子)の値は、ユニークでなくてはなりません。

eid プロパティは、イベントの標準の metadata の一部であり、 イベントに識別子を与えるものです。 送信クライアントは、イベント送出時にこれを生成し、所有アプリケーションの範囲で ユニーク性を保証しなければなりません。 特に、あるイベント型のストリームをともなうイベントは、ユニークな識別子はマストです。 これはイベント受信者が、 eid をイベントがユニークであるとして処理したり、 冪等性のチェックに使ったりするためです。

イベントを受信するシステムが eid のユニーク性のチェックすることは任意であるので、 送信者側がイベント識別子のユニーク性を保証する責務があることに注意しましょう。 イベントのユニーク識別子を生成する単純な方法は、UUIDを使うことです。

冪等 で順不同の処理をするものとしてイベントを設計しておくと、 非常にレジリエントなシステムとなります。もしイベントの処理に失敗しても、 送信者と受信者は、処理を一時停止したり、処理結果の整合性を崩すことなく、 イベント処理をスキップしたりディレイさせたりリトライしたりできます。

このように処理順を自由にするには、冪等で順不同な処理設計を明示的にやる必要があります。 イベントが元の順序を推測するのに十分な情報を含むようにしたり、業務ドメインが 順序性によらないような方法で設計するようにします。

データ変更イベントと似た共通の例として、冪等で順不同な処理は、次の情報を送る ことによって達成されます。

受信側が現在の状態にだけ関心があるのであれば、各リソースの最新イベントよりも古いものは 無視できます。 受信側がリソースの履歴にも関心があるのであれば、(部分的にでも) 順序性のある一連のイベントを 再生成するために、順番に並んだキーを使います。

イベント型の名前は、次に示すとおり オーディエンス に依存した機能本位の命名に準拠しなければなりません。 (またはそうするべきです。 MUST/SHOULD 機能本位の命名体系を使う に詳細と定義があります)

次のアプリケーション固有のレガシーな規約は、 内部 イベント型名に のみ 適用するようにしてください。

注意: 同じエンティティをデータ変更イベントとRESTful APIの両方で扱うときは、 一貫性のある名前を使うようにしましょう。

イベントの受け手は、重複したイベントを正しく処理できなくてはなりません。

大抵のメッセージブローカとデータストリーミングシステムは、"at-least-once"配信をサポートしています。 これはある特定のイベントが、必ず1回以上は受け手に届くことを保証するものです。 別の状況でも、重複したイベントが発生する可能性があります。

例えば、イベントの送信者が(ネットワークの問題によって) 受け手に届かなかったような 状況で発生します。この場合、送信者は同じイベントの再送を試みます。 こうしてイベントバスに受信者が処理すべき同一のイベントが2つ存在することになります。 同じ状態は受信者側でも起こります: イベントは正しく処理したが、その処理が確認出来ない場合です。