From 642a99592492b9da0b61a9db1b04feb47b44b0c0 Mon Sep 17 00:00:00 2001 From: Eivind Grimstad Date: Thu, 19 Feb 2026 11:37:03 +0100 Subject: [PATCH] feat: Improvements to api guidelines - Add documentationUrl to custom spectral rules - Add information about known Entur HTTP headers - Add more information about x-entur-metadata content --- .github/workflows/ci.yml | 4 +- .spectral.yml | 76 +++++++++++++++++++++++++++ guidelines.md | 76 ++++++++++++++++++++------- specs/reference-spec-with-errors.json | 3 +- 4 files changed, 135 insertions(+), 24 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1660ed6..a2475cb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,7 +26,7 @@ jobs: annotations=$(mktemp) markdown=$(mktemp) - spectral lint ./specs/reference-spec.json --ruleset ".spectral.yml" -F hint -f github-actions -o.github-actions "$annotations" -f markdown -o.markdown="$markdown" && rc=$? || rc=$? + spectral lint ./specs/reference-spec.json --ruleset ".spectral.yml" --show-documentation-url -F hint -f github-actions -o.github-actions "$annotations" -f markdown -o.markdown="$markdown" && rc=$? || rc=$? #Return code 2 means that spectral command failed to run (not linting errors), so fail workflow. if [ "$rc" -eq 2 ]; then @@ -59,7 +59,7 @@ jobs: annotations=$(mktemp) markdown=$(mktemp) - spectral lint ./specs/reference-spec-with-errors.json --ruleset ".spectral.yml" -F hint -f github-actions -o.github-actions "$annotations" -f markdown -o.markdown="$markdown" && rc=$? || rc=$? + spectral lint ./specs/reference-spec-with-errors.json --ruleset ".spectral.yml" --show-documentation-url -F hint -f github-actions -o.github-actions "$annotations" -f markdown -o.markdown="$markdown" && rc=$? || rc=$? #Return code 2 means that spectral command failed to run (not linting errors), so fail workflow. if [ "$rc" -eq 2 ]; then diff --git a/.spectral.yml b/.spectral.yml index 220b939..16cbc43 100644 --- a/.spectral.yml +++ b/.spectral.yml @@ -23,6 +23,7 @@ rules: entur-info-title: message: "The OpenAPI info section MUST include a non-empty \"title\"." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: error given: $ then: @@ -31,6 +32,7 @@ rules: entur-info-title-no-api: message: "API titles SHOULD NOT contain the word 'api'." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn given: $.info.title then: @@ -43,6 +45,7 @@ rules: # HTTP Methods entur-operation-standard-methods: message: "Operations SHOULD use standard HTTP methods (`get`, `post`, `put`, `patch`, `delete`). Invalid operation: {{property}}." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" given: $.paths[*] severity: warn then: @@ -54,6 +57,7 @@ rules: # Documentation with examples entur-example-parameter: message: "Parameters SHOULD have example values." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn recommended: false given: $.paths.*.*.parameters.* @@ -63,6 +67,7 @@ rules: entur-parameter-description: message: "Parameters SHOULD have a description." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn given: $.paths.*.*.parameters.* then: @@ -71,6 +76,7 @@ rules: entur-example-schema-property: message: "Properties in components schema SHOULD have example values." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn recommended: false #For schema properties where type is not array, or items is not a ref. (Array with ref to other schema does not need an example) @@ -81,6 +87,7 @@ rules: entur-request-body-examples: message: "Request bodies SHOULD include at least one example." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn given: $.paths.*.*.requestBody.content.* then: @@ -88,6 +95,7 @@ rules: entur-request-body-description: message: "Request bodies SHOULD have a description." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn given: $.paths.*.*.requestBody then: @@ -96,6 +104,7 @@ rules: entur-response-body-examples: message: "Response bodies SHOULD include at least one example." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn given: $.paths.*.*.responses.*.content.* then: @@ -104,6 +113,7 @@ rules: entur-operation-summary: message: "Operations SHOULD have a non-empty summary field." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn given: $.paths.*[get,post,put,patch,delete,options,head,trace] then: @@ -113,6 +123,7 @@ rules: # openapi spec version 3 entur-openapi-version-3: message: "OpenAPI specification must use version 3.x" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: error given: "$" then: @@ -126,6 +137,7 @@ rules: # Security - HTTPS requirement entur-hosts-https-only: message: "Servers MUST use HTTPS. Invalid URL: {{value}}" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: error given: $.servers[*].url then: @@ -135,6 +147,7 @@ rules: entur-hosts-not-localhost: message: "Server URLs SHOULD NOT use localhost or 127.0.0.1 as hostname. Invalid URL: {{value}}" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#21-general-design-principles" severity: warn given: $.servers[*].url then: @@ -149,6 +162,7 @@ rules: entur-permissions: message: "x-entur-permissions must match the schema" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#233-documenting-permissions-for-partner-endpoints" severity: error given: $.paths.*[get,post,put,patch,delete,options,head,trace].x-entur-permissions then: @@ -201,6 +215,7 @@ rules: entur-info-metadata-id: message: "The OpenAPI info section SHOULD include \"x-entur-metadata.id\"." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#241-identifying-a-specification" severity: warn given: $ then: @@ -209,6 +224,7 @@ rules: entur-info-metadata-id-kebab-case: message: "The \"x-entur-metadata.id\" MUST be in lower-kebab-case format. Invalid value: {{value}}" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#241-identifying-a-specification" severity: error given: $.info.x-entur-metadata.id then: @@ -216,8 +232,48 @@ rules: functionOptions: match: ^[a-z0-9]+(-[a-z0-9]+)*$ + entur-info-metadata-audience: + message: "The OpenAPI info section SHOULD include \"x-entur-metadata.audience\"." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#24-entur-metadata" + severity: warn + given: $ + then: + field: info.x-entur-metadata.audience + function: truthy + + entur-info-metadata-audience-valid: + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#24-entur-metadata" + severity: error + given: $.info.x-entur-metadata.audience + then: + function: enumeration + functionOptions: + values: + - open + - partner + - internal + + entur-info-metadata-owner: + message: "The OpenAPI info section SHOULD include \"x-entur-metadata.owner\"." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#242-specification-owner" + severity: warn + given: $ + then: + field: info.x-entur-metadata.owner + function: truthy + + entur-info-metadata-owner-valid: + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#242-specification-owner" + severity: error + given: $.info.x-entur-metadata.owner + then: + function: pattern + functionOptions: + match: ^team-[a-z0-9]+(-[a-z0-9]+)*$ + entur-info-metadata-parent-id-kebab-case: message: "The \"x-entur-metadata.parentId\" MUST be in lower-kebab-case format. Invalid value: {{value}}" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#243-merging-specifications" severity: error given: $.info.x-entur-metadata.parentId then: @@ -237,6 +293,7 @@ rules: # URL format requirements entur-paths-format: message: "Paths MUST be in kebab-case (lower case and separated with hyphens), with single slashes, and no trailing slash at end of path. Invalid path: {{property}}." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#31-resource-naming" severity: error given: $.paths.*~ then: @@ -250,6 +307,7 @@ rules: # Field naming conventions entur-query-parameters-lower-camel-case: message: "Query parameter names MUST be lowerCamelCase. Invalid name: {{value}}" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#31-resource-naming" severity: error given: $.paths.*.*.parameters[?(@.in=='query')].name then: @@ -259,6 +317,7 @@ rules: entur-path-parameters-camelCase-alphanumeric: message: "Path parameter names MUST be lowerCamelCase. Invalid name: {{value}}" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#31-resource-naming" severity: error given: $..parameters[?(@.in == 'path')].name then: @@ -268,6 +327,7 @@ rules: entur-body-fields-lower-camel-case: message: "Request and Response body field names MUST be lowerCamelCase." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#31-resource-naming" severity: error given: $..[?(@property === 'properties')] then: @@ -279,6 +339,7 @@ rules: # Server URL case requirements entur-server-urls-lowercase: message: "Server URLs MUST be in lowercase. Invalid URL: {{value}}" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#31-resource-naming" severity: error given: $.servers[*].url then: @@ -289,6 +350,7 @@ rules: # Avoid 'api' in paths entur-paths-with-api: message: "Paths SHOULD NOT contain 'api'." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#31-resource-naming" severity: warn given: $.paths.*~ then: @@ -302,6 +364,7 @@ rules: entur-info-version: message: "The OpenAPI info.version MUST be a valid semantic version (MAJOR.MINOR.PATCH format, e.g. 1.0.0)." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#32-versioning" severity: error given: $ then: @@ -327,6 +390,7 @@ rules: # Request body allowed methods entur-request-body-allowed-methods: message: "Request body is allowed only for PUT, POST, and PATCH." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#41-http-status-codes" severity: error given: - "$.paths[*].get.requestBody" @@ -340,6 +404,7 @@ rules: # HTTP method responses validation entur-get-responses-validation: message: "Invalid response code: {{property}}. GET responses MUST use one of these response codes: 200, 304, 400, 401, 403, 404, 500, 503" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#41-http-status-codes" severity: error given: $.paths.*.get.responses.*~ then: @@ -349,6 +414,7 @@ rules: entur-delete-responses-validation: message: "Invalid response code: {{property}}. DELETE responses MUST use one of these response codes: 200, 204, 400, 401, 403, 404, 409, 500, 503" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#41-http-status-codes" severity: error given: $.paths.*.delete.responses.*~ then: @@ -358,6 +424,7 @@ rules: entur-post-responses-validation: message: "Invalid response code: {{property}}. POST responses MUST use one of these response codes: 200, 201, 202, 204, 303, 400, 401, 403, 404, 409, 500, 503" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#41-http-status-codes" severity: error given: $.paths.*.post.responses.*~ then: @@ -367,6 +434,7 @@ rules: entur-put-responses-validation: message: "Invalid response code: {{property}}. PUT responses MUST use one of these response codes: 200, 204, 400, 401, 403, 404, 409, 500, 503" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#41-http-status-codes" severity: error given: $.paths.*.put.responses.*~ then: @@ -376,6 +444,7 @@ rules: entur-patch-responses-validation: message: "Invalid response code: {{property}}. PATCH responses MUST use one of these response codes: 200, 204, 400, 401, 403, 404, 409, 500, 503" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#41-http-status-codes" severity: error given: $.paths.*.patch.responses.*~ then: @@ -391,6 +460,7 @@ rules: # Error response format validation entur-rfc-9457-content-type: message: "Error responses MUST have content type application/problem+json or application/problem+xml" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#42-error-handling" severity: warn given: $.paths.*.*.responses[?(@property.match(/^(4|5)/))] then: @@ -408,6 +478,7 @@ rules: entur-rfc-9457-body-title: message: "Error responses MUST have property 'title'." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#42-error-handling" severity: error given: $.paths.*.*.responses[?(@property.match(/^(4|5)/))].content.*.schema.properties then: @@ -416,6 +487,7 @@ rules: entur-rfc-9457-body-status: message: "Error responses MUST have property 'status'." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#42-error-handling" severity: error given: $.paths.*.*.responses[?(@property.match(/^(4|5)/))].content.*.schema.properties then: @@ -424,6 +496,7 @@ rules: entur-rfc-9457-body-detail: message: "Error responses SHOULD have property 'detail' to provide additional context." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#42-error-handling" severity: warn given: $.paths.*.*.responses[?(@property.match(/^(4|5)/))].content.*.schema.properties then: @@ -442,6 +515,7 @@ rules: entur-language-headers: message: "Accept-Language and Content-Language should follow IETF BCP 47. And macrolanguages like 'no' should not be used - use 'nb' or 'nn'." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#41-language--spelling" severity: error given: - $..parameters[?(@.in=='header' && @.name=='Accept-Language')].example @@ -477,6 +551,7 @@ rules: # ET-Client-Name header not necessary entur-not-et-client-name-header: message: "Declaring header \"ET-Client-Name\" is not necessary." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#55-http-headers" severity: warn given: "$.paths[*]..parameters[?(@.in == 'header' && @.name == 'ET-Client-Name')].name" then: @@ -485,6 +560,7 @@ rules: # Header naming conventions entur-headers-hyphenated-pascal-case: message: "HTTP header names MUST be in Hyphenated-Pascal-Case. Invalid name: \"{{value}}\"." + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#55-http-headers" severity: error given: "$..parameters[?(@.in == 'header' && @.name != 'ET-Client-Name')].name" then: diff --git a/guidelines.md b/guidelines.md index 049adf4..45b6f42 100644 --- a/guidelines.md +++ b/guidelines.md @@ -4,7 +4,7 @@ ## 1. Introduction -Welcome to this API guide, designed to ensure a consistent and robust approach to developing [RESTful](https://en.wikipedia.org/wiki/REST) APIs. REST (Representational State Transfer) is an architectural style that uses standard HTTP methods to create scalable, lightweight, and maintainable services. +Welcome to Enturs API guidelines, designed to ensure a consistent and robust approach to developing [RESTful](https://en.wikipedia.org/wiki/REST) APIs. REST (Representational State Transfer) is an architectural style that uses standard HTTP methods to create scalable, lightweight, and maintainable services. ### 1.1 Purpose of the Entur API guidelines @@ -30,8 +30,8 @@ Throughout this document, these requirement levels are used: ### 1.5 Linter Coverage Throughout this document, rules are marked with the following indicators: -- :white_check_mark: Automatically enforced by [linter](README.md) -- :ballot_box_with_check: Partially checked by [linter](README.md) +- :white_check_mark: Automatically enforced by [linter](README.md#linting-your-api) +- :ballot_box_with_check: Partially checked by [linter](README.md#linting-your-api) - :eyes: Requires manual review @@ -43,8 +43,8 @@ Throughout this document, rules are marked with the following indicators: - :eyes: Consistency - Make sure the API is easy to understand and predictable - :white_check_mark: HTTP Methods - API operations **MUST** use standard HTTP methods (GET, POST, PUT, PATCH, DELETE) - :white_check_mark: Data Format - API endpoints **SHOULD** support the JSON data format, unless there is a good reason not to +- :white_check_mark: APIs **MUST** be documented using [OpenAPI 3.x](https://spec.openapis.org/oas/v3.1.2.html) - :white_check_mark: Documentation - All functionality **SHOULD** be documented with examples and descriptions -- :white_check_mark: You **MUST** use the OpenAPI V3 spec to define APIs - :white_check_mark: Encryption: All communication **MUST** be over HTTPS - :white_check_mark: You **SHOULD** not use localhost (or 127.0.0.1) host names in `info.servers`. - :white_check_mark: `info.title` **MUST** be non-empty and **MUST** not contain the word 'api'. @@ -55,7 +55,7 @@ Throughout this document, rules are marked with the following indicators: - Create the API specification before implementing the API - The specification is the primary reference for both development and documentation - Update the specification throughout development to reflect changes -- :eyes: [Lint your API spec](README.md) +- :eyes: [Lint your API spec](README.md#linting-your-api) - :eyes: Separate API specifications per target audience/visibility (public, partner, internal). An API spec **SHOULD** only contain endpoints for one target audience. This audience is used in the Developer Portal to organize APIs. - :eyes: Differentiate APIs based on the target audience: @@ -66,9 +66,11 @@ This audience is used in the Developer Portal to organize APIs. ### 2.3 Authentication and Authorization #### 2.3.1 About security in OpenAPI specs -You use `securitySchemes` inside `components` to define security schemes. You then add `security` either at the root level of the spec (to apply security to all operations), -or you add it under individual operations which are secured (this replaces the root config). +Use `securitySchemes` inside `components` to define security schemes. Then, refer to schemes using `security` either at the root level of the spec,to apply security to all operations, or under individual operations which are secured, which replaces the root config. +See: +- https://spec.openapis.org/oas/v3.1.2.html#security-scheme-object +- https://spec.openapis.org/oas/v3.1.2.html#security-requirement-object #### 2.3.2 Partner- and Internal endpoints - :eyes: These endpoints are secured using JWT tokens. This **MUST** be documented using a `jwt` scheme. @@ -118,7 +120,7 @@ Example: where `items:les` means that you need the access `les` on the operation `items`. -You can also specify that your endpoint requires multiple permissions, for example: +You can also specify that an endpoint requires multiple permissions, for example: ```json { "x-entur-permissions": { @@ -160,21 +162,34 @@ If you need to explain the required permissions in more detail, you can declare } ``` -### 2.4. Entur Metadata +### 2.4 Entur Metadata +All OpenAPI specifications published to Enturs developer portal must declare a block `x-entur-metadata` in the `info` section of the specification. -#### 2.4.1 OpenAPI spec id -- :white_check_mark: OpenAPI specifications **SHOULD** use the `id` property in the `x-entur-metadata` extension in the `info` section. +Field name|Type |Description +----------|--------|----------- +id |`string`|**REQUIRED**. Unique id for this specification. [Read more](#241-identifying-a-specification). +audience |`string`|**REQUIRED**. Who this specification is targeted to. Must be one of `"open"`, `"partner"`, `"internal"` +owner |`string`|**REQUIRED**. The Entur team responsible for this specification. [Read more](#242-specification-owner). +parentId |`string`|Id of the parent specification, used when merging. [Read more](#243-merging-specifications). Example: -```json +``` { "info": { "x-entur-metadata": { - "id": "my-specification" + "id": "items", + "owner": "team-api", + "audience": "partner" } } } ``` + + + +#### 2.4.1 Identifying a specification +- :white_check_mark: OpenAPI specifications **SHOULD** use the `id` property in the `x-entur-metadata` extension in the `info` section. + **Choosing an id** The id is used to uniquely identify a specification - each id results in an entry in the Developer Portal API catalogue, and an entry in the linting results. Because of this, the id should not change over time. The current api title (in kebab-case) could be a good id - but, of course, you should not update the id if the title changes in the future. @@ -182,13 +197,24 @@ The id should not have a `-id` suffix (or prefix). - :white_check_mark: If the id is present, it **MUST** be in lower kebab-case and contain only dashes, digits and letters (a-z). -#### 2.4.2 Merging specifications +#### 2.4.2 Specification owner +- :white_check_mark: OpenAPI specifications **SHOULD** use the `owner` property in the `x-entur-metadata` extension in the `info` section. + +The owner field declares which team is responsible for maintaining a specification. It should follow the same format as the `owner` field in the [platform orchestrator](https://github.com/entur/tf-gcp-apps/blob/main/docs/manifests/GoogleCloudApplication.md#metadataowner-owner). + +#### 2.4.3 Merging specifications Sometimes it is useful to develop some API endpoints separately, but still document them externally as a single specification. To achieve this, you can use the `x-entur-metadata` field `parentId`. This field may contain a reference the `x-entur-metadata.id` field in another published specification. Nesting is not supported. `parentId` must refer to a specification that does not itself declare a `parentId`. If there are problems with the merging, for example conflicts between the schemas, none of the specifications will be exposed. +##### Limitations +There are some limitations when merging specifications: +- `servers.url` in all specs must be a subpath of the declared `servers.url` in the "parent specification". The merged specification will use the `servers` definition from the parent specification, and the subpath of the other specifications will be added to the operation paths. If `servers` are not compatible, none of the specifications will be published. +- Root level `security` must be identical in all specs to be merged. +- If there are multiple non-equal schemas with the same name, they will be namespaced with the `x-entur-metadata.id` field. So if multiple specs declare a schema `Item` that differ from each other, there will be one schema `Item_alpha` and one schema `Item_beta`. +
Example For example, say you have three microservices, `alpha`, `beta` and `gamma`: @@ -311,7 +337,7 @@ Content-Language: en "type": "https://example.com/request-endpoint", "title": "Access forbidden", "status": 403, - "detail": "You do not have permission to access this resource..", + "detail": "You do not have permission to access this resource.", "instance": "https://example.com/something/something", "balance": 30, //Custom field "recommended-action": "Something." //Custom field @@ -366,16 +392,26 @@ Example: ### 5.4 Character Encoding - :eyes: You **MUST** encode all text in UTF-8 - :eyes: Set the Content-Type header to for example `application/json; charset=utf-8` - - Tip: test the api with international character (e.g. æ, ø, å) + - Tip: test the api with international characters (e.g. æ, ø, å) ### 5.5 HTTP Headers - :ballot_box_with_check: HTTP headers **MUST** use Hyphenated-Pascal-Case format (e.g., `Content-Type`, `Accept-Language`) -- :eyes: HTTP headers **SHOULD NOT** include the 'X-' prefix, following RFC 6648. Entur headers should have the prefix "Entur-". API:s are expected to use the prefix "Entur-" for custom headers by 2028. +- :eyes: Custom HTTP headers **SHOULD** use the prefix `Entur-`, with some exceptions. + +#### 5.5.1 Known Custom HTTP Headers +##### `ET-Client-Name` +- :white_check_mark: All endpoints **SHOULD** allow consumers to identify themselves using the request header `ET-Client-Name`. +The header is added automatically to all endpoints in a specification before publication to the developer portal. + +##### `Entur-POS` +Used to declare which "point-of-sale" a request is coming from. + +##### `Entur-Distribution-Channel` +Used to declare which distribution channel (sales channel) a request is coming from. -#### 5.5.1 ET-Client-Name -- :white_check_mark: All endpoints **SHOULD** allow that consumers identify themselves by using the header `ET-Client-Name`. The header value should be on the format `-`, e.g. `brakar-journeyplanner`. - **However**, this header is added automatically to specs when the developer portal is built (using an [OpenAPI Overlay](https://github.com/entur/developer-portal/blob/efd23abd039903b53cb5d80e8c6a41dd86437b9e/overlays/et-client-name.yml)), so specs should **not** define this header. +##### `X-Correlation-Id` +A "de-facto" standard for correlating a request throughout a microservice architecture. At Entur, this header is handled by our logging library [cloud-logging](https://github.com/entur/cloud-logging). It is automatically added to all endpoints in a specification before publication to the developer portal. ## 6. Advanced Design Patterns diff --git a/specs/reference-spec-with-errors.json b/specs/reference-spec-with-errors.json index 13fa2fc..13187de 100644 --- a/specs/reference-spec-with-errors.json +++ b/specs/reference-spec-with-errors.json @@ -11,8 +11,7 @@ "email": "support@entur.no" }, "x-entur-metadata": { - "id": "Items", - "owner": "api", + "owner": "team-Api", "audience": "public" } },