From 568242322203c4585b8d76808940458aa292d6a4 Mon Sep 17 00:00:00 2001 From: kiriakos Date: Tue, 10 Mar 2026 14:43:29 +0100 Subject: [PATCH] WIP: Segregate SHOULD from MUST guidelines This commit illustrates the restructuring some API guidelines to give SHOULD guidelines, previously embeded in MUST guidelines, their own space. - Extracted SHOULD recommendations from MUST requirements - Creating 6 new standalone SHOULD rule files with proper IDs - Updating 3 MUST rule files to reference the new SHOULD rules - Adding cross-references in both directions for discoverability The changes maintain existing documentation structure while ensuring: * MUST requirements are pure and unambiguous * SHOULD recommendations are properly separated * All rules maintain proper cross-references This is a work-in-progress proposal for discussion and review. --- .../must-follow-kafka-topic-naming-convention.md | 3 ++- ...hould-use-plural-form-for-data-topic-names.md | 14 ++++++++++++++ .../rules/must-use-absolute-profile-uris.md | 9 +++++---- ...vide-documentation-for-resolvable-profiles.md | 14 ++++++++++++++ .../should-treat-profile-uris-as-immutable.md | 14 ++++++++++++++ ...should-use-same-namespace-for-profile-uris.md | 16 ++++++++++++++++ ...solute-uris-for-custom-link-relation-types.md | 6 +++--- ...entation-for-resolvable-link-relation-uris.md | 14 ++++++++++++++ ...ould-treat-link-relation-uris-as-immutable.md | 14 ++++++++++++++ 9 files changed, 96 insertions(+), 8 deletions(-) create mode 100644 api-guidelines/async/kafka/topics/rules/should-use-plural-form-for-data-topic-names.md create mode 100644 api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-provide-documentation-for-resolvable-profiles.md create mode 100644 api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-treat-profile-uris-as-immutable.md create mode 100644 api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-use-same-namespace-for-profile-uris.md create mode 100644 api-guidelines/rest/hypermedia/link-relation-types/rules/should-provide-documentation-for-resolvable-link-relation-uris.md create mode 100644 api-guidelines/rest/hypermedia/link-relation-types/rules/should-treat-link-relation-uris-as-immutable.md diff --git a/api-guidelines/async/kafka/topics/rules/must-follow-kafka-topic-naming-convention.md b/api-guidelines/async/kafka/topics/rules/must-follow-kafka-topic-naming-convention.md index 5011cf27..2bb0ceea 100644 --- a/api-guidelines/async/kafka/topics/rules/must-follow-kafka-topic-naming-convention.md +++ b/api-guidelines/async/kafka/topics/rules/must-follow-kafka-topic-naming-convention.md @@ -37,7 +37,7 @@ de.otto.events.checkout.payment.payment-received ### Data change events Topics containing data change events must be named analogue to the contained [data event types](../../../format/cloudevents/rules/must-follow-naming-schema-for-type-context-attribute.md). -If the data topic contains data events of different types all containing the complete state of one particular entity type, the topic must be named after the entity type. The topic name should be in plural form. +If the data topic contains data events of different types all containing the complete state of one particular entity type, the topic must be named after the entity type. The topic name [should be in plural form](./should-use-plural-form-for-data-topic-names.md). Examples: @@ -53,5 +53,6 @@ This rule only applies to API topics. Topics which are not part of the API must ::: references - [MUST name events in past tense](../../../format/naming-conventions/rules/must-name-events-in-past-tense.md) +- [SHOULD use plural form for data topic names](./should-use-plural-form-for-data-topic-names.md) - [OTTO CoE Confluent Cloud - Topic Naming Conventions (internal link)](https://otto-eg.atlassian.net/wiki/x/xMPmAQ) ::: diff --git a/api-guidelines/async/kafka/topics/rules/should-use-plural-form-for-data-topic-names.md b/api-guidelines/async/kafka/topics/rules/should-use-plural-form-for-data-topic-names.md new file mode 100644 index 00000000..29148092 --- /dev/null +++ b/api-guidelines/async/kafka/topics/rules/should-use-plural-form-for-data-topic-names.md @@ -0,0 +1,14 @@ +--- +id: R200020 +--- + +# SHOULD use plural form for data topic names + +When naming data topics that contain data events of different types all representing the complete state of one particular entity type, the topic name should be in plural form. + +This convention helps distinguish entity-based topics from other topic types and follows common API naming patterns. + +::: references + +- [MUST follow kafka topic naming convention](./must-follow-kafka-topic-naming-convention.md) + ::: \ No newline at end of file diff --git a/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/must-use-absolute-profile-uris.md b/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/must-use-absolute-profile-uris.md index b96fc88b..66ee3d89 100644 --- a/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/must-use-absolute-profile-uris.md +++ b/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/must-use-absolute-profile-uris.md @@ -6,13 +6,11 @@ id: R100066 Profiles must be identified by absolute URIs (as defined in [RFC 6906](https://www.rfc-editor.org/rfc/rfc6906#section-3)) and documented in the OpenAPI specification. -The URI that identifies a profile must be treated as an identifier that should not change. -While encouraged, it does not need to be resolvable. -If it is resolvable, it should provide human-readable documentation of the profile. +The URI that identifies a profile must be treated as an identifier. [The URI should not change](./should-treat-profile-uris-as-immutable.md) over time. While encouraged, it does not need to be resolvable. [If it is resolvable, it should provide human-readable documentation](./should-provide-documentation-for-resolvable-profiles.md) of the profile. Best practice: -The URI should be in the same URL namespace as the API endpoints. +[The URI should be in the same URL namespace as the API endpoints](./should-use-same-namespace-for-profile-uris.md). For example, if all API endpoints are located at `https://api.otto.de/payment/`, the profile URIs should als be located at the same context path (e.g., `https://api.otto.de/payment/profiles/payment-method+v1`). The last part of the profile URI path must be in the format "{name}+v{version}". @@ -26,4 +24,7 @@ Examples: ::: references - [MUST use kebab-case for URIs](../../../resources/naming-conventions/rules/must-use-kebabcase-for-uris.md) +- [SHOULD treat profile URIs as immutable](./should-treat-profile-uris-as-immutable.md) +- [SHOULD provide documentation for resolvable profiles](./should-provide-documentation-for-resolvable-profiles.md) +- [SHOULD use same namespace for profile URIs](./should-use-same-namespace-for-profile-uris.md) ::: diff --git a/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-provide-documentation-for-resolvable-profiles.md b/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-provide-documentation-for-resolvable-profiles.md new file mode 100644 index 00000000..fdfbdc36 --- /dev/null +++ b/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-provide-documentation-for-resolvable-profiles.md @@ -0,0 +1,14 @@ +--- +id: R100075 +--- + +# SHOULD provide documentation for resolvable profiles + +If a profile URI is resolvable, it should provide human-readable documentation of the profile. + +This helps API consumers understand the purpose and usage of the profile. + +::: references + +- [MUST use absolute URIs for profiles](./must-use-absolute-profile-uris.md) + ::: \ No newline at end of file diff --git a/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-treat-profile-uris-as-immutable.md b/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-treat-profile-uris-as-immutable.md new file mode 100644 index 00000000..de9d0f61 --- /dev/null +++ b/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-treat-profile-uris-as-immutable.md @@ -0,0 +1,14 @@ +--- +id: R100073 +--- + +# SHOULD treat profile URIs as immutable + +The URI that identifies a profile should be treated as an identifier that does not change over time. + +This ensures that clients can rely on the URI as a stable identifier for the profile, preventing breaking changes in API contracts. + +::: references + +- [MUST use absolute URIs for profiles](./must-use-absolute-profile-uris.md) + ::: \ No newline at end of file diff --git a/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-use-same-namespace-for-profile-uris.md b/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-use-same-namespace-for-profile-uris.md new file mode 100644 index 00000000..884ffabc --- /dev/null +++ b/api-guidelines/rest/compatibility/versioning-of-incompatible-changes/rules/should-use-same-namespace-for-profile-uris.md @@ -0,0 +1,16 @@ +--- +id: R100076 +--- + +# SHOULD use same namespace for profile URIs + +Profile URIs should be in the same URL namespace as the API endpoints. + +For example, if all API endpoints are located at `https://api.otto.de/payment/`, the profile URIs should also be located at the same context path (e.g., `https://api.otto.de/payment/profiles/payment-method+v1`). + +This convention helps maintain consistency and makes it easier for API consumers to locate and understand the relationship between APIs and their profiles. + +::: references + +- [MUST use absolute URIs for profiles](./must-use-absolute-profile-uris.md) + ::: \ No newline at end of file diff --git a/api-guidelines/rest/hypermedia/link-relation-types/rules/must-use-absolute-uris-for-custom-link-relation-types.md b/api-guidelines/rest/hypermedia/link-relation-types/rules/must-use-absolute-uris-for-custom-link-relation-types.md index ae468634..0f140c29 100644 --- a/api-guidelines/rest/hypermedia/link-relation-types/rules/must-use-absolute-uris-for-custom-link-relation-types.md +++ b/api-guidelines/rest/hypermedia/link-relation-types/rules/must-use-absolute-uris-for-custom-link-relation-types.md @@ -10,9 +10,7 @@ This rule applies to APIs that have to comply with [REST maturity level 3](../.. Custom link relations must be absolute URIs (as defined in [RFC 5988](https://datatracker.ietf.org/doc/html/rfc5988#section-4.2)) and documented in the OpenAPI specification. -The URI used as the link relation type must be treated as an identifier that should not change. -While encouraged, it does not need to be resolvable. -If the URI is resolvable, it should provide human-readable documentation of the link relation type. +The URI used as the link relation type must be treated as an identifier. [The URI should not change](./should-treat-link-relation-uris-as-immutable.md) over time. While encouraged, it does not need to be resolvable. [If the URI is resolvable, it should provide human-readable documentation](./should-provide-documentation-for-resolvable-link-relation-uris.md) of the link relation type. Here's an example of an uncuried link relation that serves for demonstration only. In your APIs, you [must use curied link relation types](./must-use-curied-link-relation-types.md). @@ -32,6 +30,8 @@ In your APIs, you [must use curied link relation types](./must-use-curied-link-r - [MUST prefer IANA-registered link relation types](./must-prefer-iana-registered-link-relation-types.md) - [MUST use kebab-case for URIs](../../../resources/naming-conventions/rules/must-use-kebabcase-for-uris.md) - [MUST use curied link relation types](./must-use-curied-link-relation-types.md) +- [SHOULD treat link relation URIs as immutable](./should-treat-link-relation-uris-as-immutable.md) +- [SHOULD provide documentation for resolvable link relation URIs](./should-provide-documentation-for-resolvable-link-relation-uris.md) - [MUST implement REST maturity level 2](../../maturity-level/rules/must-implement-rest-maturity-level-2.md) - [MUST implement REST maturity level 3 for transitional APIs](../../maturity-level/rules/must-implement-rest-maturity-level-3-for-transitional-apis.md) ::: diff --git a/api-guidelines/rest/hypermedia/link-relation-types/rules/should-provide-documentation-for-resolvable-link-relation-uris.md b/api-guidelines/rest/hypermedia/link-relation-types/rules/should-provide-documentation-for-resolvable-link-relation-uris.md new file mode 100644 index 00000000..a4d15065 --- /dev/null +++ b/api-guidelines/rest/hypermedia/link-relation-types/rules/should-provide-documentation-for-resolvable-link-relation-uris.md @@ -0,0 +1,14 @@ +--- +id: R100043 +--- + +# SHOULD provide documentation for resolvable link relation URIs + +If the URI used as a link relation type is resolvable, it should provide human-readable documentation of the link relation type. + +This helps API consumers understand the purpose and usage of custom link relation types. + +::: references + +- [MUST use absolute URIs for custom link relation types](./must-use-absolute-uris-for-custom-link-relation-types.md) + ::: \ No newline at end of file diff --git a/api-guidelines/rest/hypermedia/link-relation-types/rules/should-treat-link-relation-uris-as-immutable.md b/api-guidelines/rest/hypermedia/link-relation-types/rules/should-treat-link-relation-uris-as-immutable.md new file mode 100644 index 00000000..a686e7b0 --- /dev/null +++ b/api-guidelines/rest/hypermedia/link-relation-types/rules/should-treat-link-relation-uris-as-immutable.md @@ -0,0 +1,14 @@ +--- +id: R100042 +--- + +# SHOULD treat link relation URIs as immutable + +The URI used as the link relation type should be treated as an identifier that does not change over time. + +This ensures that clients can rely on the URI as a stable identifier for the link relation type, preventing breaking changes in API contracts. + +::: references + +- [MUST use absolute URIs for custom link relation types](./must-use-absolute-uris-for-custom-link-relation-types.md) + ::: \ No newline at end of file