Clarity about Versions of API Specifications (#853)

tfrauenstein · Thomas Frauenstein · ePaul · web-flow · commit 24fa5f770429 · 2025-11-12T19:03:49.000+01:00
* Version of API Specification vs. OpenAPI Spec

* Update general-guidelines.adoc

* Update terms.adoc

* Update terms.adoc

* Update chapters/terms.adoc

Co-authored-by: Paŭlo Ebermann &lt;paul.ebermann@zalando.de&gt;

* Update chapters/terms.adoc

Co-authored-by: Paŭlo Ebermann &lt;paul.ebermann@zalando.de&gt;

* Update meta-information.adoc

* Update chapters/terms.adoc

Co-authored-by: Paŭlo Ebermann &lt;paul.ebermann@zalando.de&gt;

---------

Co-authored-by: Thomas Frauenstein &lt;thomas@zalando.de&gt;
Co-authored-by: Paŭlo Ebermann &lt;paul.ebermann@zalando.de&gt;
diff --git a/chapters/api-operation.adoc b/chapters/api-operation.adoc
@@ -5,9 +5,10 @@
 [#192]
 == {MUST} publish OpenAPI specification for APIs
 
-All service applications must publish OpenAPI specifications of their external
-APIs. While this is optional for <<219, component-internal APIs>>, we still 
-recommend to do so to profit from our API management infrastructure.
+All service applications must publish API Specifications of their external
+APIs (see <<219, API Audience definition>>). While this is optional 
+for <<219, component-internal>> APIs, we recommend doing so to profit from 
+our API management infrastructure and review services.
 
 As described in https://cloud.docs.zalando.net/howtos/api-publishing/[How to publish API Specifications (internal_link)], 
 an API specification is published with the deployment of the implementing service 
diff --git a/chapters/compatibility.adoc b/chapters/compatibility.adoc
@@ -31,9 +31,9 @@ if no API consumer is using the affected API aspects (see also <<deprecation,
 Deprecation>> guidelines).
 
 *Hint:* Please note that the compatibility guarantees are for the "on the wire"
-format. Binary or source compatibility of code generated from an API definition
+format. Binary or source compatibility of code generated from an API specification
 is not covered by these rules. If client implementations update their
-generation process to a new version of the API definition, it has to be
+generation process to a new version of the API specification, it has to be
 expected that code changes are necessary.
 
 
@@ -56,7 +56,7 @@ services in a backward-compatible way:
   not be prepared to handle it. However, enum ranges can be extended when used
   for input parameters.
 * You <<112>> that are used for output parameters and likely to
-  be extended with growing functionality. The API definition should be updated
+  be extended with growing functionality. The API specification should be updated
   first before returning new values.
 * Consider <<251>> in case a URL has to change.
 
@@ -103,8 +103,8 @@ and be explicit in what is supported:
   that already use this field but with different type.
 
 In specific situations, where a (known) input field is not needed anymore, it
-either can stay in the API definition with "not used anymore" description or
-can be removed from the API definition as long as the server ignores this
+either can stay in the API specification with "not used anymore" description or
+can be removed from the API specification as long as the server ignores this
 specific parameter.
 
 
@@ -329,6 +329,6 @@ must implement a fallback / default behavior to handle unknown new enum values -
 API owners must take care to extend enums in a compatible way that does not change the 
 semantics of already existing enum values, for instance, do not split an old enum value 
 into two new enum values. Services should only extend {x-extensible-enum} ranges, and only accept 
-and return values listed in the API definition, i.e. the API definition needs to be updated first  
+and return values listed in the API specification, i.e. the API specification needs to be updated first  
 before the service accepts/returns new values -- see also <<107>>. 
 
diff --git a/chapters/design-principles.adoc b/chapters/design-principles.adoc
@@ -118,8 +118,7 @@ implementation aspects — APIs should be stable even if we replace
 complete service implementation including its underlying technology
 stack
 
-Moreover, API definitions with standardized specification format also
-facilitate...
+Moreover, API specifications using a standard format facilitate...
 
 * single source of truth for the API specification; it is a crucial part
 of a contract between service provider and client users
@@ -147,7 +146,7 @@ and can never produce code before you have defined the complete API and
 get it confirmed by peer review.
 
 On the other hand, API First obviously is in conflict with the bad
-practice of publishing API definition and asking for peer review after
+practice of publishing API specifications and asking for peer review after
 the service integration or even the service productive operation has
 started. It is crucial to request and get early feedback — as early as
 possible, but not before the API changes are comprehensive with focus
diff --git a/chapters/events.adoc b/chapters/events.adoc
@@ -420,7 +420,7 @@ on the use of `additionalProperties`.
 [#246]
 == {MUST} use semantic versioning of event type schemas
 
-Event schemas must be versioned -- analog to <<116>> for REST API definitions.
+Event schemas must be versioned -- analog to <<116>> for REST API specifications.
 The compatibility mode interact with revision numbers in the schema
 `version` field, which follows semantic versioning (MAJOR.MINOR.PATCH):
 
diff --git a/chapters/general-guidelines.adoc b/chapters/general-guidelines.adoc
@@ -1,8 +1,7 @@
 [[general-guidelines]]
 = General guidelines
 
-The titles are marked with the corresponding labels: {MUST},
-{SHOULD}, {MAY}.
+The titles are marked with the corresponding labels: {MUST}, {SHOULD}, {MAY}.
 
 
 [#100]
@@ -22,13 +21,13 @@ You must follow the <<api-first, API First Principle>>, more specifically:
 
 
 [#101]
-== {MUST} provide API specification using OpenAPI
+== {MUST} provide API Specifications using OpenAPI
 
 We use the standard provided by the https://www.openapis.org/[OpenAPI Initiative] 
 to define API specifications. API designers are required to provide the API 
 specification using a single self-contained YAML file for better readability. 
 We encourage using https://swagger.io/specification/[OpenAPI 3.1 version], 
-especially for new APIs. The API specification files should be subject to version 
+especially for new APIs. The API specification documents should be subject to version 
 control using a source code management system, and you <<192>>.
 
 *Hint:* Our API infrastructure does not break, but might not yet fully support 
diff --git a/chapters/introduction.adoc b/chapters/introduction.adoc
@@ -14,7 +14,7 @@ external business partners to use via third-party applications.
 
 With this in mind, we’ve adopted "API First" as one of our key
 engineering principles. Microservices development begins with API
-definition outside the code and ideally involves ample peer-review
+specification outside the code and ideally involves ample peer-review
 feedback to achieve high-quality APIs. API First encompasses a set of
 quality-related standards and fosters a peer review culture including a
 lightweight review procedure. We encourage our teams to follow them to
diff --git a/chapters/json-guidelines.adoc b/chapters/json-guidelines.adoc
@@ -141,7 +141,7 @@ the upper-snake case format, e.g. `VALUE` or `YET_ANOTHER_VALUE`.
 This approach allows to clearly distinguish values from properties or other elements.
 
 **Exception:** This rule does not apply for case sensitive values sourced from outside
-API definition scope, e.g. for language codes from {ISO-639-1}[ISO 639-1], or when
+API specification scope, e.g. for language codes from {ISO-639-1}[ISO 639-1], or when
 declaring possible values for a <<137,rule 137>> [`sort` parameter].
 
 
diff --git a/chapters/meta-information.adoc b/chapters/meta-information.adoc
@@ -4,16 +4,15 @@
 
 [#218]
 == {MUST} contain API meta information
-API specifications must contain the following OpenAPI meta information
-to allow for API management:
+API specifications must contain the following 
+https://spec.openapis.org/oas/latest.html#info-object[OpenAPI meta information]:
 
-- `#/info/title` as (unique) identifying, functional descriptive name of the API
-- `#/info/version` to distinguish API specifications versions following
-  <<116, semantic rules>>
-- `#/info/description` containing a proper description of the API
-- `#/info/contact/{name,url,email}` containing the responsible team
+- `#/info/title` a (unique) identifying, functional descriptive name of the API
+- `#/info/version` the API specification document version following <<116>>
+- `#/info/description`  a proper description of the API
+- `#/info/contact/{name,url,email}` contact info of the team owning the API specification
 
-Following OpenAPI extension properties *must* be provided in addition:
+The following OpenAPI extension properties *must* be additionally provided:
 
 - `#/info/x-api-id` unique identifier of the API (<<215, see rule 215>>)
 - `#/info/x-audience` intended target audience of the API (<<219, see rule 219>>)
@@ -22,11 +21,14 @@ Following OpenAPI extension properties *must* be provided in addition:
 [#116]
 == {MUST} use semantic versioning
 
-OpenAPI allows to specify the API specification version in
-`#/info/version`. To share a common semantic of version information we
-expect API designers to comply to http://semver.org/spec/v2.0.0.html[
-Semantic Versioning 2.0] rules `1` to `8` and `11` restricted to the format
-<MAJOR>.<MINOR>.<PATCH> for versions as follows:
+OpenAPI requires the definition of API specification version via `#/info/version`. 
+Note, this API specification document version is distinct from the 
+OpenAPI Specification version (also required, e.g. `openapi: 3.1.0`), 
+or the API Implementation version -- see <<terminology>>.
+
+We expect API designers to comply to http://semver.org/spec/v2.0.0.html[
+Semantic Versioning 2.0] rules `1 - 8` and `11` with the standard version format
+<MAJOR>.<MINOR>.<PATCH> as follows:
 
 * Increment the **MAJOR** version when you make incompatible API changes
 after having aligned the changes with consumers,
@@ -52,9 +54,9 @@ Example:
 ----
 openapi: 3.1.0
 info:
+  version: 1.3.7
   title: Parcel Service API
   description: API for <...>
-  version: 1.3.7
   <...>
 ----
 
diff --git a/chapters/security.adoc b/chapters/security.adoc
@@ -6,7 +6,7 @@
 == {MUST} secure endpoints
 
 Every API endpoint must be protected and armed with authentication and authorization.
-As part of the API definition you must specify how you protect your API using
+As part of the API specification you must define how you protect your API using
 either the `http` typed `bearer` or `oauth2` typed security schemes defined in the
 https://swagger.io/docs/specification/authentication/[OpenAPI Authentication Specification].
 
diff --git a/chapters/terms.adoc b/chapters/terms.adoc
@@ -0,0 +1,13 @@
+[[terminology]]
+= Basic Terminology
+
+In the context of our REST API Guidelines, we differentiate the following entity types:
+
+* **OpenAPI Specification** (OAS) -- the REST API specification format defined as standard by the https://www.openapis.org/[OpenAPI Initiative]. We currently encourage using https://spec.openapis.org/oas/v3.1.0.html[OpenAPI 3.1 version] for API specifications.
+* **API Specification** (aka https://spec.openapis.org/oas/latest.html#openapi-description-structure[OpenAPI Description (OAD)] -- the document in OAS format specifying an API, its syntax and semantics. It should provide all information for clients to use the API, and serves as the interface definition of the API implementation.
+* **API** -- the REST API interface provided via "the wire" (HTTP+TCP/IP) by a concrete service that is deployed and running. 
+* **API Implementation** -- the implementation of the API as part of a concrete service implementation. It is typically code written in a programming language like Java or Python, and there can be multiple concrete implementations for the same API.
+
+The API Specification, of course, might differ from the actual API provided by a concrete service, because e.g. the service implementation is incomplete, not up-to-date or faulty. The API Specification that is intended to be implemented by the service <<192, must / should be published with the service deployment>>. 
+
+Note, OpenAPI allows API Specifications being composed of an entry document and URL-referenced OpenAPI Documents defining path, component or webhook elements. However, we require to provide the API specification using a single self-contained YAML document for better readability and consistent versioning and life-cycle handling -- see <<101>>. 
diff --git a/chapters/urls.adoc b/chapters/urls.adoc
@@ -143,7 +143,7 @@ filtering and <<157, embedding>>.
 API resources represent elements of the application’s domain model. Using
 domain-specific nomenclature for resource names helps developers to understand
 the functionality and basic semantics of your resources. It also reduces the
-need for further documentation outside the API definition. For example,
+need for further documentation outside the API specification. For example,
 "sales-order-items" is superior to "order-items" in that it clearly indicates
 which business object it represents. Along these lines, "items" is too general.
 
@@ -284,7 +284,7 @@ some services may choose to access the orders directly, for instance:
 
 To keep maintenance and service evolution manageable, we should follow
 "functional segmentation" and "separation of concern" design principles and do
-not mix different business functionalities in same API definition. In practice
+not mix different business functionalities in same API. In practice
 this means that the number of resource types exposed via an API should be
 limited. In this context a resource type is defined as a set of highly related
 resources such as a collection, its members and any direct sub-resources.
diff --git a/index.adoc b/index.adoc
@@ -357,6 +357,8 @@ include::chapters/introduction.adoc[]
 
 include::chapters/design-principles.adoc[]
 
+include::chapters/terms.adoc[]
+
 include::chapters/general-guidelines.adoc[]
 
 include::chapters/meta-information.adoc[]
