Skip to content

Latest commit

 

History

History
97 lines (92 loc) · 6.38 KB

changelog.adoc

File metadata and controls

97 lines (92 loc) · 6.38 KB
Raw

Changelog

This change log only contains major changes and lists major changes since October 2016.

Non-major changes are editorial-only changes or minor changes of existing guidelines, e.g. adding new error code or specific example. Major changes are changes that come with additional obligations, or even change an existing guideline obligation. Major changes are listed as "Rule Changes" below.

Hint: Most recent major changes might be missing in the list since we update it only occasionally, not with each pull request, to avoid merge commits. Please have a look at the commit list in Github to see a list of all changes.

Rule Changes

  • 2021-12-09: event id must not change in retry situations when producers [211].

  • 2021-11-24: restructuring of the document and some rules.

  • 2021-10-18: new rule [244].

  • 2021-10-12: improve clarity on {PATCH} usage in rule [148].

  • 2021-08-24: improve clarity on {PUT} usage in rule [148].

  • 2021-08-24: only use codes registered via IANA in rule [243].

  • 2021-08-17: update formats per OpenAPI 3.1 in [238].

  • 2021-06-22: [238] changed from {SHOULD} to {MUST}; consistency for rules around standards for data.

  • 2021-06-03: [104] with clear distinction of OpenAPI security schemes, favoring bearer to oauth2.

  • 2021-06-01: resolve uncertainties around 'occurred_at' semantics of event metadata.

  • 2021-05-25: [172] with API endpoint versioning as only custom media type usage exception.

  • 2021-05-05: define usage on resource-ids in {PUT} and {POST} in [148].

  • 2021-04-29: improve clarity of [133].

  • 2021-03-19: clarity on [167].

  • 2021-03-15: [242] changed from {SHOULD} to {MUST}; improve clarity around event ordering.

  • 2021-03-19: best practice section [cursor-based-pagination]

  • 2021-02-16: define how to reference models outside the api in [234].

  • 2021-02-15: improve guideline [176] — clients must be prepared to not receive problem return objects.

  • 2021-01-19: more details for {GET-with-Body} and {DELETE-with-Body} ([148]).

  • 2020-09-29: include models for headers to be included by reference in API definitions ([183])

  • 2020-09-08: add exception for legacy host names to [224]

  • 2020-08-25: change [240] from {MUST} to {SHOULD}, explain exceptions

  • 2020-08-25: add exception for self to [143] and [134].

  • 2020-08-24: change "{MUST} avoid trailing slashes" to [136].

  • 2020-08-20: change [183] from {MUST} to {SHOULD}, mention gateway-specific headers (which are not part of the public API).

  • 2020-06-30: add details to [114]

  • 2020-05-19: new sections about DELETE with query parameters and {DELETE-with-Body} in [148].

  • 2020-02-06: new rule [241]

  • 2020-02-05: add Sunset header, clarify deprecation producedure ([185], [186], [187], [188], [189], [190], [191])

  • 2020-01-21: new rule [240] (as MUST, changed later to SHOULD)

  • 2020-01-15: change "Warning" to "Deprecation" header in [189], [190].

  • 2019-10-10: remove never-implemented rule "{MUST} Permissions on events must correspond to API permissions"

  • 2019-09-10: remove duplicated rule "{MAY} Standards could be used for Language, Country and Currency", upgrade [170] from {MAY} to {SHOULD}.

  • 2019-08-29: new rule [239], extend [167] pointing to {RFC-7493}[RFC-7493]

  • 2019-08-29: new rules [236], [237]

  • 2019-07-30: new rule [238]

  • 2019-07-30: change [173] from {SHOULD} to {MUST}

  • 2019-07-30: change "{SHOULD} Null values should have their fields removed to" [123].

  • 2019-07-25: new rule [235].

  • 2019-07-18: improved cursor guideline for {GET-with-Body}.

  • 2019-06-25: change [154] from {SHOULD} to {MUST}, use OpenAPI 3 syntax

  • 2019-06-13: remove X-App-Domain from [183].

  • 2019-05-17: add X-Mobile-Advertising-Id to [183].

  • 2019-04-09 New rule [234]

  • 2019-02-19: New rule [233] extracted + expanded from [183].

  • 2019-01-24: Improve guidance on caching ([149], [227]).

  • 2019-01-21: Improve guidance on idempotency, introduce idempotency-key ([229], [231]).

  • 2019-01-16: Change [135] from {MAY} to {SHOULD NOT}

  • 2018-10-19: Add ordering_key_field to event type definition schema ([197], [203])

  • 2018-09-28: New rule [228]

  • 2018-09-13: replaced OpenAPI 2.0 syntax with OpenAPI 3.0 in the example snippets

  • 2018-08-10: New rule [226]

  • 2018-07-12: Add audience field to event type definition ([197])

  • 2018-06-11: Introduced new naming guidelines for host, permission, and event names.

  • 2018-01-10: Moved meta information related aspects into new chapter [meta-information].

  • 2018-01-09: Changed publication requirements for API specifications ([192]).

  • 2017-12-07: Added best practices section including discussion about optimistic locking approaches.

  • 2017-11-28: Changed OAuth flow example from password to client credentials in [security].

  • 2017-11-22: Updated description of X-Tenant-ID header field

  • 2017-08-22: Migration to Asciidoc

  • 2017-07-20: Be more precise on client vs. server obligations for compatible API extensions.

  • 2017-06-06: Made money object guideline clearer.

  • 2017-05-17: Added guideline on query parameter collection format.

  • 2017-05-10: Added the convention of using RFC2119 to describe guideline levels, and replaced book.could with book.may.

  • 2017-03-30: Added rule that permissions on resources in events must correspond to permissions on API resources

  • 2017-03-30: Added rule that APIs should be modelled around business processes

  • 2017-02-28: Extended information about how to reference sub-resources and the usage of composite identifiers in the [143] part.

  • 2017-02-22: Added guidance for conditional requests with If-Match/If-None-Match

  • 2017-02-02: Added guideline for batch and bulk request

  • 2017-02-01: [180]

  • 2017-01-18: Removed "Avoid Javascript Keywords" rule

  • 2017-01-05: Clarification on the usage of the term "REST/RESTful"

  • 2016-12-07: Introduced "API as a Product" principle

  • 2016-12-06: New guideline: "Should Only Use UUIDs If Necessary"

  • 2016-12-04: Changed OAuth flow example from implicit to password in [security].

  • 2016-10-13: [172]

  • 2016-10-10: Introduced the changelog. From now on all rule changes on API guidelines will be recorded here.