diff --git a/docs/release/trg-0/TRG 6.02 API Versioning.md b/docs/release/trg-0/TRG 6.02 API Versioning.md new file mode 100644 index 000000000000..ceb5a93cceed --- /dev/null +++ b/docs/release/trg-0/TRG 6.02 API Versioning.md @@ -0,0 +1,64 @@ +--- +title: TRG 6.02 - API Versioning +sidebar_position: 1 +--- + +:::caution +Proposed release date: "mandatory after": 01st of May 2024 +::: + +| Status | Created | Post-History | +|------------|--------------|----------------------------------------| +| Draft | 30-Nov-2023 | Initial contribution | + +## Why + +For publicly available APIs a versioning mechanism is required, so that all APIs are versioned the same way. + +Note that for APIs accessible only via EDC, the API-version is included in the EDC asset and not the URL. This is described in CX-0018. + +## What + +This TRG applies to all APIs created within Tractus-X, but does not apply where existing standards (e.g. Data Space Protocol) are implemented where contracticting behavoir is required in order to adhere to that standard. + +For APIs that are called through an EDC asset, the version information hast to be included as a property in the EDC asset. This needs to be done in accordance with Catena-X standard CX-0018. More information and guidance is available there. + +## Description + +For public REST-APIs (= called through an EDC aspect), the Version number **must** be included in the URL. + +Example: `https://example.com/api/v2/customers` + +A standard **should** offer the following aliases as well (meaning they all answer identically to HTTP requests): + +`https://example.com/api/v2.1/customers` + +`https://example.com/api/latest/customers` + +For the version in the URL, semantic versioning **must** be used. + +Old endpoints (that have been offered bevor) and are not supported anymore **should** respond with an appropriate HTTP 30x status code and the new location (URL). + +For example, when v3 of an API is released, an request to `https://example.com/api/v2/customers` would return HTTP 301 (moved permanently) and point to `https://example.com/api/v3/customers` + +Queries and fragments **may** be used, so the following example is valid: + + https://example.com:443/messaging/v1/messages?textContains=AMG#resultlist + \___/ \______________/\___________________/\_______________/ \________/ + | | | | | + scheme authority path query fragment + +Note that the structure of the URL needs to be chosen mindfully. For example: + +* `https://example.com/api/customers/v2` → this is bad idea since you might want to rename 'customers' to something else in the future +* `https://example.com/api/customers/` → does not make it clear which version is used. It might be the latest, but some developers might not notice and assume the API is stable for ever +* `https://example.com/api/v2.4.8/customers/` → not recommended since a patch (according to semantic versioning) is always backward compatible the need for this can be questioned. Adding the patch level to the URL forces clients to frequently to adapt to a new URL. + +Further rules and recommendations on URL design: + +* It is **recommended** to use nouns over verbs. For example, use `/customers` instead of `/getCustomers/` +* It is **recommended** to use plural nouns. For example, use `/customers/` instead of `/customer/` +* It is **recommended** to use the concrete object, not a abstraction. For example, use `/customers/` instead of `/persons/` +* The technical identifier **should** be part of the path, not the query. For example, use `/customers/12345/` instead of `/customers?key=12345` +* Only English words **must** be used. For example, use `/customers/` instead of `/kunden/` +* Camel case **should not** be used in the URI, but it MAY be used in the query or fragment part. For example, use `/vehicleorders/`, `/vehicle-orders/` or `/vehicle_orders/` instead of `/VehicleOrders/` diff --git a/docs/release/trg-0/trg-0.md b/docs/release/trg-0/trg-0.md index 077ef444b86f..7cdacb745981 100644 --- a/docs/release/trg-0/trg-0.md +++ b/docs/release/trg-0/trg-0.md @@ -6,6 +6,7 @@ title: TRG 0 - Changelog & Drafts | Created | Post-History | |--------------|-----------------------------------------------------------------------------------------------| +| 04-Dec-2023 | TRG 6.02 added Draft for TRG API Versioning | | 04-Dec-2023 | TRG 7.06 update Shared UI Components / NPM library | | 09-Oct-2023 | TRG 4.06 add base image for hashicorp vault | | 29-Sep-2023 | TRG 4.02 / 06 add Alpine Linux to list of container base images |