From 2afe0ebe97ea963811c6eb3a4850aa10e0802d64 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Thu, 9 Nov 2023 08:52:31 +0100 Subject: [PATCH 1/3] docs: decision record about API versioning --- .../2023-11-09-api-versioning/README.md | 83 +++++++++++++++++++ docs/developer/decision-records/README.md | 2 + 2 files changed, 85 insertions(+) create mode 100644 docs/developer/decision-records/2023-11-09-api-versioning/README.md diff --git a/docs/developer/decision-records/2023-11-09-api-versioning/README.md b/docs/developer/decision-records/2023-11-09-api-versioning/README.md new file mode 100644 index 00000000000..5ced18fd386 --- /dev/null +++ b/docs/developer/decision-records/2023-11-09-api-versioning/README.md @@ -0,0 +1,83 @@ +# Consistent Versioning of external APIs + +## Decision + +Going forward, all our external APIs will be versioned consistently across all endpoints and controllers. This means, +that the +Management API (to name a prominent example) will have the version encoded same URL within the same major version. + +## Rationale + +Currently, every module that contributes an API can have its own versioning model. For example, at the time of writing +some APIs are available under `/v2/...`, some are available under `/v3/...` and some without a version specifier. + +This can be confusing to developers who want to consume the API, because they not only need different base paths for +every API, they also need to re-check every endpoint when a new version of EDC is released, because every API can change +individually. + +Therefor we will use consistent versioning across _all_ client-facing APIs. At the time of writing, this includes just +the Management API. + +## Approach + +### Versioning scheme + +Following the general semantics of SemVer, we will distinguish between a breaking change (major version bump) and +non-breaking and patch changes (minor/patch version bump). The major version will be represented in the URL: + +``` +https://some.host.com/api/management/v4/... +``` + +This means, client code only needs to be updated on major version changes of an API. + +> Only major versions are represented in the URL + +> Minor or patch updates will **not** be represented in the URL, and we will **not** host multiple minor/patch versions +> of an API at any given time. + +Consequently, when multiple major versions of an API are available, every versioned URL (e.g. `/v3/assets`) effectively +contains the _latest_ version, so for instance `/v3/assets` would effectively point to version `3.1.4` of the Management +API. + +> The same exact version is used for the entire Management API, we do **not** version independent modules or controllers + +> The version of an API is independent of the version of EDC. + +### Delegation mechanism for controllers + +Not every endpoint changes from version to version, that means we will have to make the _same_ controller available +under _multiple_ URL paths as we do not want to duplicate controllers. There are several potential ways we could make +this work: + +- Declare the `@Path` as [wildcard](https://docs.oracle.com/javaee/7/api/javax/ws/rs/Path.html) +- implement a custom interceptor, that parses the path and delegates to the correct controller + +These are as yet untested and need further investigation with regard to the following aspects: + +- do the come up as individual endpoints in the OpenAPI documentation? +- is there a significant impact w.r.t. resource consumption? + +### Storing and publishing version information + +A new endpoint will be available that provides exact information about the version of the API. The path and the response +schema is TBD. + +The version of an API must be stored in a file that is available at runtime. Every change to an API must increase that +version property. The `gradle.properties` file would be the obvious choice, however we would have to craft a way to +access that information at runtime. + +### Publishing APIs to SwaggerHub + +Ultimately, we will move away from publishing our APIs under the EDC version, and will publish them only under their +own version. Every update (major, minor, patch,...) will be published to SwaggerHub. +For this, we will have to update our Swagger-publish workflow quite significantly and read the +API [version information](#storing-and-publishing-version-information). + +### Maintenance/deprecation model + +As a standard M/O EDC will expose at most two versions of an API at any given time. The older one must be marked +as `deprecated` both in code and in Swagger. + +All maintenance (bugfixes, patches, improvements) will **only** be made to the most recent API. Deprecated APIs will +**not** receive any maintenance. diff --git a/docs/developer/decision-records/README.md b/docs/developer/decision-records/README.md index 37096d56c90..ce1bb6670c2 100644 --- a/docs/developer/decision-records/README.md +++ b/docs/developer/decision-records/README.md @@ -48,3 +48,5 @@ - [2023-08-01 Default datasource](2023-08-01-default-datasource) - [2023-08-07 Generic properties](./2023-08-07-generic-properties) - [2023-09-07 Policy Monitor](./2023-09-07-policy-monitor) +- [2023-10-04 JSON-LD Scopes](./2023-10-04-json-ld-scopes) +- [2023-11-09 API Versioning](./2023-11-09-api-versioning) From 07c845cb5ed82eec087cb7ec1042a461895ac6f7 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> Date: Thu, 9 Nov 2023 13:13:41 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: alexandrudanciu <80531692+alexandrudanciu@users.noreply.github.com> Co-authored-by: Jim Marino --- .../2023-11-09-api-versioning/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/developer/decision-records/2023-11-09-api-versioning/README.md b/docs/developer/decision-records/2023-11-09-api-versioning/README.md index 5ced18fd386..5f7938ee71a 100644 --- a/docs/developer/decision-records/2023-11-09-api-versioning/README.md +++ b/docs/developer/decision-records/2023-11-09-api-versioning/README.md @@ -4,7 +4,7 @@ Going forward, all our external APIs will be versioned consistently across all endpoints and controllers. This means, that the -Management API (to name a prominent example) will have the version encoded same URL within the same major version. +Management API (to name a prominent example) will encode the same version number consistently across all its existing service endpoint URLs, within a major version. ## Rationale @@ -15,7 +15,7 @@ This can be confusing to developers who want to consume the API, because they no every API, they also need to re-check every endpoint when a new version of EDC is released, because every API can change individually. -Therefor we will use consistent versioning across _all_ client-facing APIs. At the time of writing, this includes just +Therefore, we will use consistent versioning across _all_ client-facing APIs. At the time of writing, this includes just the Management API. ## Approach @@ -46,7 +46,7 @@ API. ### Delegation mechanism for controllers -Not every endpoint changes from version to version, that means we will have to make the _same_ controller available +Not every endpoint changes from version to version. We will have to make the _same_ controller available under _multiple_ URL paths as we do not want to duplicate controllers. There are several potential ways we could make this work: @@ -55,8 +55,8 @@ this work: These are as yet untested and need further investigation with regard to the following aspects: -- do the come up as individual endpoints in the OpenAPI documentation? -- is there a significant impact w.r.t. resource consumption? +- do controllers appear as individual endpoints in the OpenAPI documentation? +- is there a significant impact w.r.t. resource consumption and response time? ### Storing and publishing version information From 851a68bfde36abdc0bf6eb4f390856f9e7984714 Mon Sep 17 00:00:00 2001 From: Paul Latzelsperger Date: Thu, 9 Nov 2023 16:56:37 +0100 Subject: [PATCH 3/3] DEPENDENCIES --- DEPENDENCIES | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/DEPENDENCIES b/DEPENDENCIES index cc9d59d2da8..980f2e36cb3 100644 --- a/DEPENDENCIES +++ b/DEPENDENCIES @@ -146,21 +146,21 @@ maven/mavencentral/io.swagger.core.v3/swagger-annotations/2.2.8, Apache-2.0, app maven/mavencentral/io.swagger.core.v3/swagger-core-jakarta/2.2.15, Apache-2.0, approved, #5929 maven/mavencentral/io.swagger.core.v3/swagger-core/2.2.15, Apache-2.0, approved, #9265 maven/mavencentral/io.swagger.core.v3/swagger-core/2.2.8, Apache-2.0, approved, #9265 -maven/mavencentral/io.swagger.core.v3/swagger-integration-jakarta/2.2.15, Apache-2.0, approved, clearlydefined +maven/mavencentral/io.swagger.core.v3/swagger-integration-jakarta/2.2.15, Apache-2.0, approved, #11475 maven/mavencentral/io.swagger.core.v3/swagger-integration/2.2.15, Apache-2.0, approved, #10352 -maven/mavencentral/io.swagger.core.v3/swagger-jaxrs2-jakarta/2.2.15, Apache-2.0, approved, clearlydefined +maven/mavencentral/io.swagger.core.v3/swagger-jaxrs2-jakarta/2.2.15, Apache-2.0, approved, #11477 maven/mavencentral/io.swagger.core.v3/swagger-jaxrs2/2.2.15, Apache-2.0, approved, #9814 maven/mavencentral/io.swagger.core.v3/swagger-models-jakarta/2.2.15, Apache-2.0, approved, #5919 maven/mavencentral/io.swagger.core.v3/swagger-models/2.2.15, Apache-2.0, approved, #10353 maven/mavencentral/io.swagger.core.v3/swagger-models/2.2.8, Apache-2.0, approved, #10353 -maven/mavencentral/io.swagger.parser.v3/swagger-parser-core/2.1.10, None, restricted, #11314 +maven/mavencentral/io.swagger.parser.v3/swagger-parser-core/2.1.10, None, restricted, #11478 maven/mavencentral/io.swagger.parser.v3/swagger-parser-v2-converter/2.1.10, Apache-2.0, approved, #9330 maven/mavencentral/io.swagger.parser.v3/swagger-parser-v3/2.1.10, Apache-2.0, approved, #9323 maven/mavencentral/io.swagger.parser.v3/swagger-parser/2.1.10, None, restricted, #11316 maven/mavencentral/io.swagger/swagger-annotations/1.6.9, Apache-2.0, approved, #3792 -maven/mavencentral/io.swagger/swagger-compat-spec-parser/1.0.64, None, restricted, #11282 +maven/mavencentral/io.swagger/swagger-compat-spec-parser/1.0.64, None, restricted, #11479 maven/mavencentral/io.swagger/swagger-core/1.6.9, Apache-2.0, approved, #4358 -maven/mavencentral/io.swagger/swagger-models/1.6.9, LicenseRef-scancode-proprietary-license, restricted, #11330 +maven/mavencentral/io.swagger/swagger-models/1.6.9, LicenseRef-scancode-proprietary-license, restricted, #11476 maven/mavencentral/io.swagger/swagger-parser/1.0.64, Apache-2.0, approved, #4359 maven/mavencentral/jakarta.activation/jakarta.activation-api/1.2.1, EPL-2.0 OR BSD-3-Clause OR GPL-2.0-only with Classpath-exception-2.0, approved, ee4j.jaf maven/mavencentral/jakarta.activation/jakarta.activation-api/2.1.0, EPL-2.0 OR BSD-3-Clause OR GPL-2.0-only with Classpath-exception-2.0, approved, ee4j.jaf