Add the reworked API Versioning chapter + annotations in ChangeLog #273
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
BirgitBoss
reviewed
Apr 9, 2024
documentation/IDTA-01002-3/modules/ROOT/pages/IDTA-01002_HTTP-REST-API.adoc
Outdated
Show resolved
Hide resolved
BirgitBoss
reviewed
Apr 9, 2024
|
|
||
| Upcoming implementations of AAS related servers may implement the version prefix “*api/v<X.Y>/*” to provide information of the specific major version regarding AAS Part 2 version, where <X> denotes the implemented major version and <Y> denotes the minor version, e.g. “api/v3.0/” (see Figure 4). | ||
| As multiple versions will be supported in the future, an AAS ecosystem consisting of Registry / Discovery services as well as AAS Repository, Submodel (standalone), or AAS (standalone) services should share a consistent version. Therefore, a consistent interface description in the form of OpenAPI documents shall be provided with each major version. |
There was a problem hiding this comment.
by whom? the openAPI documents are part of the specification itself, aren't they?
I would remove the complete sentence.
BirgitBoss
reviewed
Apr 9, 2024
| ==== | ||
| Note:* all URLs mentioned in this document regarding the REST mapping of the AAS APIs have to be understood with this prefix in mind. | ||
| ==== | ||
| Upcoming compatibility constraints regarding newer versions will be elaborated in further iterations of this document and related technical descriptions (OpenAPI specification). |
There was a problem hiding this comment.
add in outlook section but not in text part: will typically be forgotten. And I do not know exactly which constraints we do have in mind?
BirgitBoss
reviewed
Apr 9, 2024
|
|
||
| The versioning scheme for AAS API related services follows semantic versioning footnote:[http://semver.org]. Very briefly, this defines version numbers as a format following: <MAJOR>.<MINOR>.<PATCH>. | ||
| There are different solutions regarding API versioning involving URL-based versioning, query parameter-based versioning, as well as HTTP header-oriented solutions using custom or standard headers. |
There was a problem hiding this comment.
what is query parameter-based versioning? You have a source for the three classifications?
There was a problem hiding this comment.
These are old statements, I have only put them at a different position in the subchapter to keep it readable.
BirgitBoss
reviewed
Apr 9, 2024
documentation/IDTA-01002-3/modules/ROOT/pages/IDTA-01002_HTTP-REST-API.adoc
Outdated
Show resolved
Hide resolved
BirgitBoss
reviewed
Apr 9, 2024
documentation/IDTA-01002-3/modules/ROOT/pages/IDTA-01002_HTTP-REST-API.adoc
Outdated
Show resolved
Hide resolved
BirgitBoss
reviewed
Apr 9, 2024
|
|
||
| Finally, it is recommended to include an additional "/description” endpoint into each service to further denote information about APIs / servers capabilities. This endpoint provides further information about the API and its supported profiles. The “/description” will be extended with additional information in later versions. | ||
| Upcoming implementations of AAS related servers may implement the version prefix “*api/v<X.Y>/*” to provide information of the specific major version regarding AAS Part 2 version, where <X> denotes the implemented major version and <Y> denotes the minor version, e.g. “api/v3.0/” (see Figure 4). |
There was a problem hiding this comment.
why mentioning this if we recommend to use V3 only?
There was a problem hiding this comment.
This paragraph is from the old version of the chapter, I have removed it.
BirgitBoss
reviewed
Apr 9, 2024
| Finally, it is recommended to include an additional "/description” endpoint into each service to further denote information about APIs / servers capabilities. This endpoint provides further information about the API and its supported profiles. The “/description” will be extended with additional information in later versions. | ||
| Upcoming implementations of AAS related servers may implement the version prefix “*api/v<X.Y>/*” to provide information of the specific major version regarding AAS Part 2 version, where <X> denotes the implemented major version and <Y> denotes the minor version, e.g. “api/v3.0/” (see Figure 4). | ||
|
|
||
| Finally, it is recommended to include an additional "/description” endpoint into each service to further denote information about APIs / servers capabilities. This endpoint provides further information about the API and its supported profiles, and in particular the version of the profiles. The “/description” will be extended with additional information in later versions. |
There was a problem hiding this comment.
it is not recommended, our profile definitions request it
There was a problem hiding this comment.
Future ==> Summary and Outlook, please not in text (it typcially stays forever...)
BirgitBoss
reviewed
Apr 9, 2024
documentation/IDTA-01002-3/modules/ROOT/pages/IDTA-01002_HTTP-REST-API.adoc
Outdated
Show resolved
Hide resolved
BirgitBoss
reviewed
Apr 9, 2024
|
|
||
| Additionally, “Release candidates” are variants of the implementation of the denoted major version. For example, “3.1.0 RC2” should be interpreted as the second (alternative) release candidate for version 3.1.0. This will still result in the version prefix “/api/v3.1/”. | ||
| Upcoming implementations of AAS related servers may implement the version prefix “api/v<X>/” to provide information of the specific major version regarding AAS Part 2 version, where <X> denotes the implemented major version, e.g. “api/v3/” (see Figure 4). As minor releases of one major version must not contain any breaking changes, the declaration of the minor version can be omitted. |
There was a problem hiding this comment.
what do you mean? whose impelmentations? the aasx server in Eclipse Digital Twin?
BirgitBoss
requested changes
Apr 9, 2024
There was a problem hiding this comment.
see comments +
- line 19: The OpenAPI specification of the HTTP/REST APIs can be found at SwaggerHub. ==> in github? but the links are all to swaggerHub
- line 23: Schema Part 1 in reality is the Schema Part 1 and embedded data specifications, in V3.1 it is IDTA-01003-a, the IEC61360 data specification for concept descriptions
- line 76 For the example “[{"name": "globalAssetId","value": "http://example.company/myAsset"},{"name": "myOwnInternalAssetId","value": "12345ABC"}]”, the resulting base64url-encoded value of the query parameter is +
“?assetIds=W3sibmFtZSI6ICJnbG9iYWxBc3NldElkIiwidmFsdWUiOiAiaHR0cDovL2V4YW1wbGUuY29tcGFueS9teUFzc2V0In0seyJuYW1lIjogIm15T3duSW50ZXJuYWxBc3NldElkIiwidmFsdWUiOiAiMTIzNDVBQkMifV0”. + (formatting) - 101: A specific AAS API version uses specific related versions of the metamodel as defined in Clause 1.2. -- really?
- The first figure with the example should not contain V3.0 because we are not recommending it. It should be V3 only.
BirgitBoss
reviewed
Apr 12, 2024
|
|
||
| As multiple versions will be supported in the future, an AAS ecosystem consisting of Registry / Discovery services as well as AAS Repository, Submodel (standalone), or AAS (standalone) services should share a consistent version. Therefore, a consistent interface description in the form of OpenAPI documents shall be provided with each major version. | ||
| Nevertheless, AAS servers may decide to use different paths depending on their context, see Figure 5. A client shall not assume that the pattern from Figure 4 is supported by all servers. |
There was a problem hiding this comment.
Suggested change
| Nevertheless, AAS servers may decide to use different paths depending on their context, see Figure 5. A client shall not assume that the pattern from Figure 4 is supported by all servers. | |
| Nevertheless, AAS servers may decide to use different paths depending on their context, see Figure 5. The fragment before the functional endpoint is not necessarily the version information itself, it may also be a tenant ID or any other information the server decides to use. A client shall not assume that the pattern from Figure 4 is supported by every server. |
…REST-API.adoc Co-authored-by: Birgit Boss <[email protected]>
…REST-API.adoc Co-authored-by: Birgit Boss <[email protected]>
…REST-API.adoc Co-authored-by: Birgit Boss <[email protected]>
…REST-API.adoc Co-authored-by: Birgit Boss <[email protected]>
|
We need to discuss how we continue with such findings. They target the V3.0.2 changes, which are still maintained in Word. "Misusing" PRs for V3.1.0 makes it very hard to track and fix them. I'll put it on the agenda for our next group meeting. |
BirgitBoss
approved these changes
Apr 28, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changes have been introduced with Bugfix Version 3.0.2 and need to be reflected in V3.1.0 as well.