本文書では要求レベルのキーワドとして、 "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ファーストの原則にしたがわなければなりません。

私たちは OpenAPI (以前はSwaggerと呼ばれていたもの)を、API定義の標準として使っています。APIの設計者はAPI仕様ファイルを、可読性向上のため*YAML*を使って書きます。私たちのツールがOpenAPI 3.0をサポートするまでは、*OpenAPI 2.0*を使うようにしてください。

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

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

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

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

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

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

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

追加の注意:

例:

それぞれのAPIは明示的に、オーナーを割り当て、ユニークでイミュータブルなAPI識別子によって、識別されなければなりません。 APIは進化し続けるので、API識別子を除くすべてのAPIの要素が変わる可能性があります。 API識別子にもとづき一連のAPI仕様を特定し、私たちはAPIのライフサイクルを監視し、APIの履歴や進化を管理しています。 例えば、私たちは API Linter Zallを使って、以前のAPIバージョンに対して、 APIの変更の互換性チェックとセマンティックバージョンの正しさを検証しています。

API識別子は、Open API仕様の`info`-ブロックで定義します。 そしてこれは、次の仕様に準拠しなければなりません。

セマンティックAPI バージョン と一緒にAPI識別子のアプリケーションが、APIの履歴を 期待どおりに反映していることを保証するのは、APIオーナーの責務です。

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

例:

API識別子物語 により情報があります。

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

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

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

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

例:

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

上記例はセキュリティ標準として、エンドポイントへのアクセスを認証するのに クライアント認証フローのOAuth2を使った際の定義です。 さらに、スコープセクションを使って2つのAPIアクセス権を定義しています。 エンドポイントの権限の使い方は後述します。次のセクションを参照ください。

securityDefinitions でOAuthトークンを取得するフローを指定するのは、ほとんど意味がありません。 APIエンドポイントは、どうOAuthトークンが生成されようが気にする必要はありません。 不幸にも flow フィールドは必須であり、消すことはできません。 APIエンドポイントは、常に flow: application を設定し、 この情報は無視するべきです。

すべてのAPIはアクセス権(ここではスコープと呼ぶ) を定義する必要があります。 そして、すべてのAPIエンドポイントには、少なくとも1つのスコープを割り当てる必要があります。 前セクションで示したように、スコープはAPI仕様ごとに名前とその説明によって定義します。 スコープ名を決めるとき、次のルールを参照するようにしてください。

APIはデフォルトでは標準のスコープを使うべきです。大概のユースケースでは、(read と write 違いで)特定のAPIへのアクセスを制限することは、荷主か小売か、カスタマか運用スタッフか、といった クライアントの種類によってアクセスを制御するのに十分なものです。 私たちはスコープが多く、細かくなりすぎないようにしたいと考えています。 それはなんら付加価値を産まず複雑さだけが増していくからです。 ただ、APIが異なるオーナーには異なるリソースを返すような状況下では、 リソース固有のスコープは意味があるかもしれません。

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

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

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

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

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

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

私たちは互換性を維持したAPIの拡張を強く推奨し、バージョニングは最後の手段とします。(以下に示すルールをみてください 113,114 ) サービスプロバイダが従うガイドライン(rule 107) と コンシューマが従うガイドライン(rule 108) で、バージョニングなしに(ポステルの法則を胸に)互換性をたもった変更ができるようになります。

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

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

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

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

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

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

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

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

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

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

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

APIフォーマットは additionalProperties をfalseと宣言してはなりません。将来的にオブジェクトが拡張されるのを防ぐためです。

このガイドラインはデフォルトの拡張可能性に焦点を当てているのであって、 ある状況下では単なる値として 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`メディアタイプのままにしておきましょう。

ヒント: このIssueのコメント は(フラグメントが削除されることを利用した)回避策に言及していますが、 OpenAPIは今のところ、公式にはコンテントネゴシエーションをサポートしていません。 新しいバージョンしか文書化しないという別の手もありますが、サーバは古いバージョンも受け付けるようにしなければなりません。

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

URIバージョニングとは、/v1/customers のように、パスに(メジャー)バージョン番号を含ませる方法です。

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

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

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

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

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

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

廃止予定フェーズの間、 Warning ヘッダを付けましょう。 (RFC 7234 - Warning header をみてください)。 Warning が付いていたら、 warn-code は 299 を指定し、 warn-text は "The path/operation/parameter/…​ {name} is deprecated and will be removed by {date}. Please see {link} for details." の形式にしましょう。 link先は、なぜAPIがもはやサポートされないかと、クライアントがすべきことを記述した ドキュメントにします。 `Warning`ヘッダを付加しても、クライアントに対しAPI停止の同意を得たとはいえません。

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

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

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

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

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

ここで「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に置き換えることができます。

共通して使われるSwagger/OpenAPIでは、フィールドがnull値をもつことをサポートしていません。 (もし必須としてマークされていなければ、フィールドごと消すという意図です)

しかしnull値をもつフィールドをクライアント-サーバ間で送受信することは避けられません。 またnullが意味のある値となる場合もあります。JSON Merge Patch (RFC 7382)は、 プロパティの削除を示すのにnullを使います。

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

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

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

OpenAPI フォーマット の"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に文法が含まれます )

上記で定義されているものを使いましょう。

例:

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

例:

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

例:

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

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

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

たいていの場合、サービスによって提供されるすべてのリーソースは、公開APIの一部です。 それゆえにベースパスであるルート"/"は利用可能にしておくべきです。 もしサービスが非公開、内部APIをサポートしなきゃいけなくなったら、ベースパスとして"/api"を 付けておけば、公開APIと非公開APIのリソースを明確に分離しておくことができます。

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

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

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」とするのは、一般的過ぎます。

いくつかの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をする ようにできます。 特に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メソッドの意味に沿うようにしましょう。

HTTPメソッドには以下の性質の有無に違いがあります。

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

クエリパラメータで値の集合を渡すには、いくつかの方法があります。 どれか1つを選択し、API定義に明示します。 OpenAPIプロパティの collectionFormat は、クエリパラメータのフォーマットを指定するのに使われます。

複数値をもつクエリパラメータには、csv または multi いずれかのフォーマットを使うべきです。

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

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

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

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

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

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

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

クライアントのリクエストレートをコントロールしたいAPIは、 '429 Too Many Requests'レスポンス コードを使います。 もしクライアントがリクエストレートを越えたら、リクエストは実行されなくなります。 そのようなレスポンスは、クライアントにそのような追加の情報を知らせるために、 ヘッダをセットしなくてはなりません。その手段は次の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リクエストヘッダを 通じてそれをコントロールできます。see also RFC 7231 Section 5.3.4.

サーバもまたContent-Encodingヘッダを通じて、gzip圧縮が使われていることを明示すべきです。

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

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

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

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

APIがキャッシュをサポートすることが意図されていれば、キャッシュ境界(すなわち、 Cache-Control と Vary ヘッダを付加することによって生存期間とキャッシュ制約) を定義することによって、これを明記しなければなりません。 (RFC-7234 を注意深く読んでください。)

キャッシュは実に多くのことを考慮しなくてはなりません。例えば、レスポンス情報の一般的な キャッシュ可能性、SSLやOAuthを使ってエンドポイントを保護するためのガイドライン、 リソースのアップデートや無効化ルール、複数のコンシューマインスタンスの存在など。 結果としてキャッシュは、最良の場合「複雑」で、最悪の場合「何の役にも立たない」ものになるでしょう。 API設計者がよくこれを理解していることが示されない限りは、RESTful APIに関して クライアントサイドでのキャッシュや透過的なHTTPキャッシュは避けるべきです。

デフォルトでは、APIは Cache-Control: no-cache ヘッダをセットすべきです。

注意: このデフォルトセッティングをドキュメントに書く必要はありません。 たいていのフレームワークは、レスポンスに自動的に付与するからです。 しかし、このデフォルトから外れる場合は、しっかりとドキュメント化しなくてはなりません。

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

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

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

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

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

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

これらのコレクションは現在のページの項目を保持するために、items`属性をもつべきです。 コレクションは必要ならば自身や現在のページについてのメタデータ(例えば`index`や`page_size)を付加してもよいです。

明確な必要性がない限り、APIに総件数をもたせるのは避けるべきです。 総件数を取得するがために、フルスキャンを引き起こす複雑なクエリやフィルタを発行することになり 性能問題を引き起こすことがよくあるためです (例えば、カウントとるためにすべての要素をスキャンする必要があります)。 これはAPIの実装の詳細に踏み込んだ話ですが、あなたの能力と、カウント機能を提供することとを よく考えるのは重要なことです

もしコレクションが他のリソースへのリンクから構成されていれば、 コレクションの名前は、 IANA IANAにLink Relationsとして登録されたものにするべきです。ただし複数形にしましょう。

例えば、"記事"のサービスは、`authors`へのハイパーリンクのコレクションを以下のように表現できます。

私たちは 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を使うべきです。

ページネーション可能なコレクションの一番よい表現方法は、 ページネーション を見てください。

私たちは RFC 5988 で定義された Link ヘッダ は、 JSONメディアタイプとは同時に使わないようにしています。 JSONペイロードに直接組み込まれたリンクを、共通化されていないリンクヘッダの文法よりも優先します。

構造化データを転送するためにJSONエンコードされたボディのペイロードを使いましょう。 JSONペイロードは RFC-7159 にしたがわなければなりません。 トップレベルの構造としては(可能であれば)、将来拡張可能なように、シリアライズしたオブジェクトとします。 具体例はMay: 適用可能なところではページネーションリンクを使うを見てください。

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

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

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

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

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

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

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

金額の10進の値はその通貨での単一の値で表記します。 小数点の前の数値はメジャーユニットであり、小数点の後ろの数値はマイナーユニットです。 ビットコインのトランザクションのように、高い精度を要求する業務もあるので、API仕様に 明記していない限りは、アプリケーションは制限なしの精度を受け取れるように 準備しておかなければなりません。 ユーロの正しい表記を例示します。

特定の言語でこのインタフェースを実装したり計算したりする際には、 "amount"フィールドを決して`float`や`double`型に変換してはなりません。 そうしないと精度が失われてしまいます。代わりにJavaの BigDecimalのような正確なフォーマットを使いましょう。 詳細は Stack Overflow

いくつかのJSONパーサ(例えばNodeJS)は、デフォルトでnumberをfloatに変換してしまいます。 議論 (internal link)を経て、私たちは金額のフォーマットに"decimal"を使うことに決めました。 OpenAPIフォーマットの標準ではないけれど、パーサがnumberをfloatやdoubleに変換してしまうことを避けることができるからです。

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

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

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

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

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

Prefer をサポートするAPIは、 これまた RFC7240 で定義された Preference-Applied ヘッダを返すかもしれません。 これはプリファレンスが適用されたかどうかを指し示すのに使われます。

リソースが作成、更新されるときは、コンフリクトの発生を検知し、'更新データのロスト’や '重複して作成される’問題を防ぐ必要があります。 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における楽観ロック セクションも参照ください。

一般的なルールとして、独自HTTPヘッダは避けるべきというのがあります。 end-to-endで複数サービスを Still they can be useful in cases where context needs to be passed through multiple services in an end-to-end fashion. APIの一部分だけではなく、それに続くやり取りに必要とされる文脈情報も与えるような ところで独自ヘッダを用いるのは、妥当なユースケースです。

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

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

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

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

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

すべてのZalandoの独自ヘッダは、End-to-Endのヘッダです。 footnoteref:[header-types, HTTP/1.1 standard (RFC-7230) では 2つのタイプのヘッダが定義されています。end-to-end と hop-by-hop です。

end-to-endヘッダは、リクエストまたはレスポンスの最終的な受け取り手まで 伝達しなければなりません。 一方、hop-by-hopヘッダは、単一のコネクションの間でしか有効でないものです。]

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

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

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

すべてのサービスアプリケーションは、外に向けた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のイベントカテゴリレジストリは、イベントのバリデーションの宣言や 強化戦略、ストリームの中でどうパーティショニングされるかのような補足情報が 記述できるようになっています。

イベントカテゴリ はイベント型の一般的な分類です。 ガイドラインは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 の使用についてのガイドラインは、 互換性 の章の「Open APIの定義をデフォルトで拡張に対してオープンとして扱う」を参照ください。

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

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

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

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

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

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

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

イベントの型はこれらの命名規約にしたがいましょう。

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

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

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

以下のフレームワークは、OpenAPI YAMLファイルを使って、特にAPIファーストをサポートするよう設計されています。

Swagger/OpenAPI のホームページにも一覧があります Community-Driven Language Integrations が、それらのほとんどがAPIファーストのアプローチには合わないものです。

These utility libraries support you in implementing various parts of our RESTful API guidelines (sorted alphabetically):