From 4e04db5f0b9ed1467c267bd0c8fa276c8ccf4758 Mon Sep 17 00:00:00 2001 From: Andrei Matei Date: Tue, 16 Jun 2026 16:31:33 +0100 Subject: [PATCH] chore(ipa): rename guideline docs from .md to .mdx Pure extension rename + relative-link update; no content changes. CLOUDP-377138 --- ipa/general/{0001.md => 0001.mdx} | 0 ipa/general/{0002.md => 0002.mdx} | 0 ipa/general/{0003.md => 0003.mdx} | 2 +- ipa/general/{0004.md => 0004.mdx} | 4 ++-- ipa/general/{0005.md => 0005.mdx} | 0 ipa/general/{0101.md => 0101.mdx} | 36 +++++++++++++++---------------- ipa/general/{0102.md => 0102.mdx} | 0 ipa/general/{0103.md => 0103.mdx} | 17 ++++++++------- ipa/general/{0104.md => 0104.mdx} | 8 +++---- ipa/general/{0105.md => 0105.mdx} | 6 +++--- ipa/general/{0106.md => 0106.mdx} | 9 ++++---- ipa/general/{0107.md => 0107.mdx} | 21 +++++++++--------- ipa/general/{0108.md => 0108.mdx} | 9 ++++---- ipa/general/{0109.md => 0109.mdx} | 4 ++-- ipa/general/{0110.md => 0110.mdx} | 0 ipa/general/{0111.md => 0111.mdx} | 6 +++--- ipa/general/{0112.md => 0112.mdx} | 0 ipa/general/{0113.md => 0113.mdx} | 28 ++++++++++++------------ ipa/general/{0114.md => 0114.mdx} | 4 ++-- ipa/general/{0115.md => 0115.mdx} | 4 ++-- ipa/general/{0116.md => 0116.mdx} | 0 ipa/general/{0117.md => 0117.mdx} | 4 ++-- ipa/general/{0118.md => 0118.mdx} | 2 +- ipa/general/{0119.md => 0119.mdx} | 0 ipa/general/{0120.md => 0120.mdx} | 4 ++-- ipa/general/{0121.md => 0121.mdx} | 0 ipa/general/{0122.md => 0122.mdx} | 0 ipa/general/{0123.md => 0123.mdx} | 2 +- ipa/general/{0124.md => 0124.mdx} | 14 ++++++------ ipa/general/{0125.md => 0125.mdx} | 0 ipa/general/{0126.md => 0126.mdx} | 0 ipa/general/{0127.md => 0127.mdx} | 26 +++++++++++----------- ipa/general/{0128.md => 0128.mdx} | 10 ++++----- ipa/general/{0129.md => 0129.mdx} | 30 +++++++++++++------------- ipa/general/{0130.md => 0130.mdx} | 0 ipa/{index.md => index.mdx} | 0 ipa/sdks/{0900.md => 0900.mdx} | 0 37 files changed, 127 insertions(+), 123 deletions(-) rename ipa/general/{0001.md => 0001.mdx} (100%) rename ipa/general/{0002.md => 0002.mdx} (100%) rename ipa/general/{0003.md => 0003.mdx} (96%) rename ipa/general/{0004.md => 0004.mdx} (93%) rename ipa/general/{0005.md => 0005.mdx} (100%) rename ipa/general/{0101.md => 0101.mdx} (74%) rename ipa/general/{0102.md => 0102.mdx} (100%) rename ipa/general/{0103.md => 0103.mdx} (83%) rename ipa/general/{0104.md => 0104.mdx} (86%) rename ipa/general/{0105.md => 0105.mdx} (92%) rename ipa/general/{0106.md => 0106.mdx} (87%) rename ipa/general/{0107.md => 0107.mdx} (85%) rename ipa/general/{0108.md => 0108.mdx} (88%) rename ipa/general/{0109.md => 0109.mdx} (96%) rename ipa/general/{0110.md => 0110.mdx} (100%) rename ipa/general/{0111.md => 0111.mdx} (94%) rename ipa/general/{0112.md => 0112.mdx} (100%) rename ipa/general/{0113.md => 0113.mdx} (76%) rename ipa/general/{0114.md => 0114.mdx} (97%) rename ipa/general/{0115.md => 0115.mdx} (85%) rename ipa/general/{0116.md => 0116.mdx} (100%) rename ipa/general/{0117.md => 0117.mdx} (98%) rename ipa/general/{0118.md => 0118.mdx} (92%) rename ipa/general/{0119.md => 0119.mdx} (100%) rename ipa/general/{0120.md => 0120.mdx} (91%) rename ipa/general/{0121.md => 0121.mdx} (100%) rename ipa/general/{0122.md => 0122.mdx} (100%) rename ipa/general/{0123.md => 0123.mdx} (97%) rename ipa/general/{0124.md => 0124.mdx} (76%) rename ipa/general/{0125.md => 0125.mdx} (100%) rename ipa/general/{0126.md => 0126.mdx} (100%) rename ipa/general/{0127.md => 0127.mdx} (81%) rename ipa/general/{0128.md => 0128.mdx} (92%) rename ipa/general/{0129.md => 0129.mdx} (80%) rename ipa/general/{0130.md => 0130.mdx} (100%) rename ipa/{index.md => index.mdx} (100%) rename ipa/sdks/{0900.md => 0900.mdx} (100%) diff --git a/ipa/general/0001.md b/ipa/general/0001.mdx similarity index 100% rename from ipa/general/0001.md rename to ipa/general/0001.mdx diff --git a/ipa/general/0002.md b/ipa/general/0002.mdx similarity index 100% rename from ipa/general/0002.md rename to ipa/general/0002.mdx diff --git a/ipa/general/0003.md b/ipa/general/0003.mdx similarity index 96% rename from ipa/general/0003.md rename to ipa/general/0003.mdx index e016ab1..6456499 100644 --- a/ipa/general/0003.md +++ b/ipa/general/0003.mdx @@ -22,7 +22,7 @@ for use in APIs, they also follow consistent patterns and style. - IPAs **should** begin with an introduction (with no additional heading). - IPAs **must** include the current state, formatted as [admonition](https://docusaurus.io/docs/markdown-features/admonitions). - - Valid states are listed in [IPA-1](0001.md) + - Valid states are listed in [IPA-1](0001.mdx) - The guidance section **may** include subsections that elaborate further on the details - If necessary, the IPA **may** include a “Further Reading” section after diff --git a/ipa/general/0004.md b/ipa/general/0004.mdx similarity index 93% rename from ipa/general/0004.md rename to ipa/general/0004.mdx index 5947781..a84b3e4 100644 --- a/ipa/general/0004.md +++ b/ipa/general/0004.mdx @@ -44,12 +44,12 @@ resource attributes with client-defined values. [Terraform](https://www.terraform.io/) is an example of such a client. -To learn more, see [IPA-127](0127.md). +To learn more, see [IPA-127](0127.mdx). ### Side Effects Side effects are operations that create, update, or delete resources — or mutate -[client-owned fields](0111.md#single-owner-fields) of a resource — unrelated to +[client-owned fields](0111.mdx#single-owner-fields) of a resource — unrelated to the target of the original request. For example, a create operation that also updates a parent resource's configuration, or an update on resource X that silently rewrites client-owned fields on resource Y. diff --git a/ipa/general/0005.md b/ipa/general/0005.mdx similarity index 100% rename from ipa/general/0005.md rename to ipa/general/0005.mdx diff --git a/ipa/general/0101.md b/ipa/general/0101.mdx similarity index 74% rename from ipa/general/0101.md rename to ipa/general/0101.mdx index 15e19ba..c5913ed 100644 --- a/ipa/general/0101.md +++ b/ipa/general/0101.mdx @@ -9,11 +9,11 @@ Resource-oriented design is a pattern for specifying APIs based on several high-level design principles: - The fundamental building blocks of an API are - [individually named resources](0102.md) (nouns) and the relationships and + [individually named resources](0102.mdx) (nouns) and the relationships and hierarchy that exist between them -- A small number of [standard methods](0103.md) (verbs) provide the semantics +- A small number of [standard methods](0103.mdx) (verbs) provide the semantics for most common operations - - [Custom methods](0109.md) are available in situations where the standard + - [Custom methods](0109.mdx) are available in situations where the standard methods do not fit. - Stateless protocol: Each interaction between the client and the server are independent, and both the client and server have clear roles @@ -26,7 +26,7 @@ When designing an API, consider the following (roughly in logical order): - The relationships and hierarchies between those resources - The schema of each resource - The methods (verbs) each resource provides rely as much as possible on the - [standard verbs](0103.md) + [standard verbs](0103.mdx) ### Resources @@ -57,9 +57,9 @@ resource. The methods can be: -- The standard methods ([Get](0104.md), [List](0105.md), [Create](0106.md), - [Update](0107.md), [Delete](0108.md)) -- [Custom methods](0109.md) +- The standard methods ([Get](0104.mdx), [List](0105.mdx), [Create](0106.mdx), + [Update](0107.mdx), [Delete](0108.mdx)) +- [Custom methods](0109.mdx) The following table illustrates the relationship between resources and the standard methods: @@ -72,29 +72,29 @@ standard methods: | Delete | None | None | | List | None | Are the resources | -- A resource **must** support at minimum [Get](0104.md) +- A resource **must** support at minimum [Get](0104.mdx) - Clients **must** be able to validate the state of resources after performing - a mutation such as [Create](0106.md), [Update](0107.md), or - [Delete](0108.md) -- A resource **must** also support [List](0105.md) except for - [singleton resources](0113.md) where more than one resource is not possible + a mutation such as [Create](0106.mdx), [Update](0107.mdx), or + [Delete](0108.mdx) +- A resource **must** also support [List](0105.mdx) except for + [singleton resources](0113.mdx) where more than one resource is not possible - APIs **should** prefer standard methods over custom methods - - [Custom methods](0109.md) help define functionality that does not cleanly + - [Custom methods](0109.mdx) help define functionality that does not cleanly map to any of the standard methods ### Read-Only Resources Read-only resources are resources that cannot be modified by API consumers. -- Read-only resources **must** have [Get](0104.md) and [List](0105.md) methods -- Read-only resources **must not** have [Create](0106.md), [Update](0107.md), or - [Delete](0108.md) methods -- Read-only resources **may** have [custom methods](0109.md) as appropriate +- Read-only resources **must** have [Get](0104.mdx) and [List](0105.mdx) methods +- Read-only resources **must not** have [Create](0106.mdx), [Update](0107.mdx), + or [Delete](0108.mdx) methods +- Read-only resources **may** have [custom methods](0109.mdx) as appropriate - All response schema properties for read-only resources **must** be marked as read-only - In OpenAPI, this means all properties **must** have `readOnly: true` - All fields in read-only resources are server-owned. For guidance on - server-owned fields, see [IPA-111](0111.md#single-owner-fields) + server-owned fields, see [IPA-111](0111.mdx#single-owner-fields) - Unsupported operations on read-only resources **should** return `405 Not Allowed` - Unsupported operations **must not** be documented diff --git a/ipa/general/0102.md b/ipa/general/0102.mdx similarity index 100% rename from ipa/general/0102.md rename to ipa/general/0102.mdx diff --git a/ipa/general/0103.md b/ipa/general/0103.mdx similarity index 83% rename from ipa/general/0103.md rename to ipa/general/0103.mdx index a81a4fb..5a37917 100644 --- a/ipa/general/0103.md +++ b/ipa/general/0103.mdx @@ -18,22 +18,22 @@ that a service can perform on behalf of the consumer. - In such scenarios where a side effect is necessary, a custom method **should** be used - A side effect specifically includes mutating - [client-owned fields](0111.md#single-owner-fields) of any resource other + [client-owned fields](0111.mdx#single-owner-fields) of any resource other than the target of the request. The dependent mutation **must** be performed through the dependent resource's own endpoint; if the operation is fundamentally multi-resource by design, it **must** be modeled as a custom method per the rule above. - Side effects limited to read-only or - [effective values](0111.md#effective-values) of another resource **may** + [effective values](0111.mdx#effective-values) of another resource **may** occur in standard methods. - Standard methods **must** guarantee [atomicity](https://en.wikipedia.org/wiki/Atomicity_%28database_systems%29) - In cases where atomicity cannot be guaranteed, consider in the following order: - A new sub-resource with the appropriate methods - - A [singleton-resource](0113.md) for the corresponding section - - [Custom methods](0109.md), for example, an `Add` or `Remove` operation for - repeated fields + - A [singleton-resource](0113.mdx) for the corresponding section + - [Custom methods](0109.mdx), for example, an `Add` or `Remove` operation + for repeated fields If a standard method is unsuitable, then custom methods offer a lesser, but still valuable level of consistency, helping the user reason about the scope of @@ -48,15 +48,16 @@ Selecting a custom method may be valuable for: ### Response bodies - Every endpoint **must** support a versioned JSON content type (e.g. - `application/vnd.atlas.YYYY-MM-DD+json`), per [IPA-900](../sdks/0900.md). + `application/vnd.atlas.YYYY-MM-DD+json`), per [IPA-900](../sdks/0900.mdx). Additional content types (e.g. `+csv`) **may** be offered alongside JSON. - When a response body is returned as a JSON content type, it **must** be a JSON object with a fixed set of named properties at the root. - Top-level arrays, primitives, or objects with dynamic (unknown) keys at the root are prohibited because they cannot be consistently typed by schema-based clients and tooling. - - Collections **must** be wrapped in an envelope object per [IPA-110](0110.md) - (e.g. `{"results": [...], "links": [...], "totalCount": 42}`). + - Collections **must** be wrapped in an envelope object per + [IPA-110](0110.mdx) (e.g. + `{"results": [...], "links": [...], "totalCount": 42}`). ### Naming diff --git a/ipa/general/0104.md b/ipa/general/0104.mdx similarity index 86% rename from ipa/general/0104.md rename to ipa/general/0104.mdx index 813a3cb..3ebd39b 100644 --- a/ipa/general/0104.md +++ b/ipa/general/0104.mdx @@ -14,7 +14,7 @@ example, `/groups/{groupId}/clusters/{clusterName}`) to retrieve that resource. - The purpose of the Get method is to return data from a single resource - The HTTP verb **must** be [`GET`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) -- The method **must not** [cause side effects](0103.md) +- The method **must not** [cause side effects](0103.mdx) - The request **must not** include a body - API producers **should** implement as a `Response` suffixed object - A `Response` object **must not** include fields available only on creation @@ -40,7 +40,7 @@ GET /groups/${groupId}/clusters/${clusterName} - Operation ID **should** be followed by a noun or compound noun - The noun(s) in the Operation ID **should** be the collection identifiers from the resource identifier in singular form - - If the resource is a [singleton](0113.md), the last noun **may** be the + - If the resource is a [singleton](0113.mdx), the last noun **may** be the plural form of the collection identifier Examples: @@ -52,5 +52,5 @@ Examples: ### Error Handling -See [IPA-114: Errors](0114.md) for guidance on error handling and documentation, -in particular Authentication, Authorization and Not Found. +See [IPA-114: Errors](0114.mdx) for guidance on error handling and +documentation, in particular Authentication, Authorization and Not Found. diff --git a/ipa/general/0105.md b/ipa/general/0105.mdx similarity index 92% rename from ipa/general/0105.md rename to ipa/general/0105.mdx index 3ed5b52..7d937ef 100644 --- a/ipa/general/0105.md +++ b/ipa/general/0105.mdx @@ -16,10 +16,10 @@ which lives within that collection. - The purpose of the List method is to return data from a finite collection - The HTTP verb **must** be [`GET`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) -- The method **must not** [cause side effects](0103.md) +- The method **must not** [cause side effects](0103.mdx) - The request **must not** include a body - The response body **should** consist of the same resource object returned by - the [Get](0104.md) method + the [Get](0104.mdx) method - The object **may** include any [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) `links` field from the individual resource @@ -50,4 +50,4 @@ Examples: ## Further Reading -- [IPA-110: Pagination](0110.md) +- [IPA-110: Pagination](0110.mdx) diff --git a/ipa/general/0106.md b/ipa/general/0106.mdx similarity index 87% rename from ipa/general/0106.md rename to ipa/general/0106.mdx index c619f20..1b7ea3b 100644 --- a/ipa/general/0106.md +++ b/ipa/general/0106.mdx @@ -13,9 +13,9 @@ collection. - APIs **should** provide a create method for resources unless it is not valuable for users to do so - - [Read-only resources](0101.md#read-only-resources) **must not** have a + - [Read-only resources](0101.mdx#read-only-resources) **must not** have a Create method - - [Singleton resources](0113.md) **must not** have a Create method + - [Singleton resources](0113.mdx) **must not** have a Create method - The purpose of the create method is to create a new resource in a collection - The HTTP verb **must** be [`POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) @@ -25,7 +25,7 @@ collection. - In OpenAPI, this means that the `Request` object **must not** include fields with `readOnly: true` - The response body **should** be the same resource returned by the - [Get](0104.md) method + [Get](0104.mdx) method - Create operations **must not** accept query parameters - Query parameters are usually a sign of a side effect that standard methods **must not** cause @@ -40,7 +40,8 @@ POST /groups/${groupId}/clusters ### Error Handling -See [IPA-114: Errors](0114.md) for guidance on error handling and documentation. +See [IPA-114: Errors](0114.mdx) for guidance on error handling and +documentation. ### Naming diff --git a/ipa/general/0107.md b/ipa/general/0107.mdx similarity index 85% rename from ipa/general/0107.md rename to ipa/general/0107.mdx index 60121f5..aae3645 100644 --- a/ipa/general/0107.md +++ b/ipa/general/0107.mdx @@ -13,9 +13,9 @@ resource. - APIs **should** provide an update method for resources unless it is not valuable for users to do so - - [Read-only resources](0101.md#read-only-resources) **must not** have an + - [Read-only resources](0101.mdx#read-only-resources) **must not** have an Update method - - [Read-only singleton resources](0113.md#read-only-singleton-resources) + - [Read-only singleton resources](0113.mdx#read-only-singleton-resources) **must not** have an Update method - The purpose of the Update method is to make changes to the resources without causing side effects @@ -28,18 +28,18 @@ resource. - `PUT` is strongly discouraged because it becomes a backward-incompatible change to add fields to the resource - The request body **must** contain the resource being updated, i.e. the - resource or parts of the resource returned by the [Get method](0104.md) + resource or parts of the resource returned by the [Get method](0104.mdx) - API producers **should** implement as a `UpdateRequest` suffixed object - A `UpdateRequest` object **must** include only input fields - In OpenAPI, this means that the `UpdateRequest` object **must not** include fields with `readOnly: true` - The response body **should** be the same resource returned by the - [Get method](0104.md) + [Get method](0104.mdx) - The Update method **should** return the complete resource to avoid complexities for clients - The Update method **must** respect the client provided values, or lack thereof, for all fields in the request (see - [Client-owned fields](0111.md#single-owner-fields)) + [Client-owned fields](0111.mdx#single-owner-fields)) - For partial resource updates, the Update method **must** only update fields included in the request body and leave all other fields unchanged - For full resource replacements, the Update method **must** update the full @@ -50,7 +50,7 @@ resource. request, the server **should** unset the field or reset it to its default value - The server **should** return a - [validation error](0114.md#validation-errors) if the client provides + [validation error](0114.mdx#validation-errors) if the client provides `null` for a field that is not nullable and cannot be unset - Update operations **must not** accept query parameters - Query parameters are usually a sign of a side effect that standard methods @@ -61,7 +61,7 @@ resource. return a 200 response with no change to the resource - Resources **should** provide a single canonical update operation - If a resource has multiple Update methods, it's possible one, or all of - them, **may** be [custom methods](0109.md) + them, **may** be [custom methods](0109.mdx) Example @@ -71,7 +71,8 @@ PATCH /groups/${groupId}/clusters/{clusterName} ### Error Handling -See [IPA-114: Errors](0114.md) for guidance on error handling and documentation. +See [IPA-114: Errors](0114.mdx) for guidance on error handling and +documentation. ### Naming @@ -81,8 +82,8 @@ See [IPA-114: Errors](0114.md) for guidance on error handling and documentation. - Operation ID **should** be followed by a noun or compound noun - The noun(s) in the Operation ID **should** be the collection identifiers from the resource identifier in singular form - - If the resource is a [singleton resource](0113.md), the last noun **may** be - the plural form of the collection identifier + - If the resource is a [singleton resource](0113.mdx), the last noun **may** + be the plural form of the collection identifier Examples: diff --git a/ipa/general/0108.md b/ipa/general/0108.mdx similarity index 88% rename from ipa/general/0108.md rename to ipa/general/0108.mdx index 5e0052f..11a1cb5 100644 --- a/ipa/general/0108.md +++ b/ipa/general/0108.mdx @@ -13,9 +13,9 @@ resource. - APIs **should** provide a Delete method for resources unless it is not valuable for users to do so - - [Read-only resources](0101.md#read-only-resources) **must not** have a + - [Read-only resources](0101.mdx#read-only-resources) **must not** have a Delete method - - [Singleton resources](0113.md) **must not** have a Delete method + - [Singleton resources](0113.mdx) **must not** have a Delete method - The HTTP verb **must** be [`DELETE`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) - The response **should** be empty @@ -26,7 +26,7 @@ resource. - The Delete method **should** succeed if and only if a resource was present and was successfully deleted - If the resource did not exist, the method **should** respond with a - `NOT FOUND` [error](0114.md) + `NOT FOUND` [error](0114.mdx) Example @@ -52,7 +52,8 @@ DELETE /groups/{groupId}/clusters/{clusterName}?cascading=true ### Error Handling -See [IPA-114: Errors](0114.md) for guidance on error handling and documentation. +See [IPA-114: Errors](0114.mdx) for guidance on error handling and +documentation. ### Naming diff --git a/ipa/general/0109.md b/ipa/general/0109.mdx similarity index 96% rename from ipa/general/0109.md rename to ipa/general/0109.mdx index 9b13547..ee18439 100644 --- a/ipa/general/0109.md +++ b/ipa/general/0109.mdx @@ -5,7 +5,7 @@ state: adopt # IPA-109: Custom Methods -[Resource-oriented design](0101.md) uses custom methods to provide a means to +[Resource-oriented design](0101.mdx) uses custom methods to provide a means to express arbitrary actions that are difficult to model using only the standard methods. @@ -59,7 +59,7 @@ POST /groups/${groupId}/clusters/${clusterName}:removeNode ### Declarative-friendly resources - Declarative-friendly resources **should not** use custom methods. To learn - more, see [IPA-127](0127.md). + more, see [IPA-127](0127.mdx). - Custom methods require manual curation, implementation, and review for API tooling, which increases feature latency. - Declarative-friendly tools are unable to automatically determine what to do diff --git a/ipa/general/0110.md b/ipa/general/0110.mdx similarity index 100% rename from ipa/general/0110.md rename to ipa/general/0110.mdx diff --git a/ipa/general/0111.md b/ipa/general/0111.mdx similarity index 94% rename from ipa/general/0111.md rename to ipa/general/0111.mdx index 80667fa..b571d1c 100644 --- a/ipa/general/0111.md +++ b/ipa/general/0111.mdx @@ -21,7 +21,7 @@ Fields **must** have a single owner, whether that is the client or the server. - Server-owned fields **must** be documented as read-only - In OpenAPI, server-owned fields **must** have `readOnly: true` - Server-owned fields **must not** be accepted in request bodies for - [Create](0106.md) or [Update](0107.md) operations + [Create](0106.mdx) or [Update](0107.mdx) operations - Server-owned fields **may** be omitted if appropriate to the API - API Producers **should** document whether the server-owned field is guaranteed, or if it can be omitted in the response @@ -36,8 +36,8 @@ Fields **must** have a single owner, whether that is the client or the server. :::note For resources where all fields are server-owned, see -[read-only resources](0101.md#read-only-resources) and -[read-only singleton resources](0113.md#read-only-singleton-resources). +[read-only resources](0101.mdx#read-only-resources) and +[read-only singleton resources](0113.mdx#read-only-singleton-resources). ::: diff --git a/ipa/general/0112.md b/ipa/general/0112.mdx similarity index 100% rename from ipa/general/0112.md rename to ipa/general/0112.mdx diff --git a/ipa/general/0113.md b/ipa/general/0113.mdx similarity index 76% rename from ipa/general/0113.md rename to ipa/general/0113.mdx index 1e3d244..3843842 100644 --- a/ipa/general/0113.md +++ b/ipa/general/0113.mdx @@ -12,14 +12,14 @@ parent. ## Guidance - Singleton resources **must not** have a user-provided or system-generated ID -- Singleton resources **must not** define the [Create](0106.md) or - [Delete](0108.md) standard methods +- Singleton resources **must not** define the [Create](0106.mdx) or + [Delete](0108.mdx) standard methods - The singleton is implicitly created or deleted when its parent is created or deleted -- Singleton resources **must** define the [Get](0104.md) method -- Singleton resources **should** define the [Update](0107.md) method, unless the - resource is [read-only](0113.md#read-only-singleton-resources) -- Singleton resources **may** define [custom methods](0109.md) as appropriate +- Singleton resources **must** define the [Get](0104.mdx) method +- Singleton resources **should** define the [Update](0107.mdx) method, unless + the resource is [read-only](0113.mdx#read-only-singleton-resources) +- Singleton resources **may** define [custom methods](0109.mdx) as appropriate Example @@ -31,19 +31,19 @@ PATCH /groups/${groupId}/settings ### Read-Only Singleton Resources -Read-only singleton resources are [singleton resources](0113.md) that cannot be +Read-only singleton resources are [singleton resources](0113.mdx) that cannot be modified by API consumers. -- Read-only singleton resources **must** have only the [Get](0104.md) method -- Read-only singleton resources **must not** have [Create](0106.md), - [Update](0107.md), or [Delete](0108.md) methods -- Read-only singleton resources **may** have [custom methods](0109.md) as +- Read-only singleton resources **must** have only the [Get](0104.mdx) method +- Read-only singleton resources **must not** have [Create](0106.mdx), + [Update](0107.mdx), or [Delete](0108.mdx) methods +- Read-only singleton resources **may** have [custom methods](0109.mdx) as appropriate, provided they do not modify the resource - All response schema properties for read-only singleton resources **must** be marked as read-only - In OpenAPI, this means all properties **must** have `readOnly: true` - All fields in read-only singleton resources are server-owned. For guidance - on server-owned fields, see [IPA-111](0111.md#single-owner-fields) + on server-owned fields, see [IPA-111](0111.mdx#single-owner-fields) - Unsupported operations on read-only singleton resources **should** return `405 Not Allowed` - Unsupported operations **must not** be documented @@ -51,8 +51,8 @@ modified by API consumers. ### Resetting Singleton Resources Singleton resources can be restored to their default state without deleting the -parent resource. For such cases, a `:reset` [custom method](0109.md) **must** be -used. +parent resource. For such cases, a `:reset` [custom method](0109.mdx) **must** +be used. - The `:reset` custom method name **must** be reserved exclusively for restoring singleton resources to their default state diff --git a/ipa/general/0114.md b/ipa/general/0114.mdx similarity index 97% rename from ipa/general/0114.md rename to ipa/general/0114.mdx index 350048d..2f3dd73 100644 --- a/ipa/general/0114.md +++ b/ipa/general/0114.mdx @@ -22,7 +22,7 @@ error-handling code. in case of an error by adding a `help` field - `help` **must** include a short description as description - `help` **must** include a link to the documentation url -- [Methods](0103.md) **must** document any possible error and their associated +- [Methods](0103.mdx) **must** document any possible error and their associated [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) ### Authentication and Authorization @@ -64,7 +64,7 @@ Validation errors typically occur when: - APIs **must not** accept invalid requests and silently modify field values to make them valid - This violates the principle that client-owned fields must not be modified by - the server (see [IPA-111](0111.md#single-owner-fields)) + the server (see [IPA-111](0111.mdx#single-owner-fields)) - APIs **should** make the best effort to validate as much as possible of the request and include all validation errors in the field `badRequestDetail` - `badRequestDetail` **must** include an array of fields and each field diff --git a/ipa/general/0115.md b/ipa/general/0115.mdx similarity index 85% rename from ipa/general/0115.md rename to ipa/general/0115.mdx index e6c50db..08d24a8 100644 --- a/ipa/general/0115.md +++ b/ipa/general/0115.mdx @@ -17,8 +17,8 @@ any relevant details that would normally be in the response headers. - If `envelope` is set to `true` for individual resources - The response **must** include the field `status` as the HTTP status code - The response **must** include the field `content` as the requested resource -- If `envelope` is set to `true` for [Paginated](0110.md) resources the existing - response **must** include the field `status` as the HTTP status code +- If `envelope` is set to `true` for [Paginated](0110.mdx) resources the + existing response **must** include the field `status` as the HTTP status code ### Generated API Clients diff --git a/ipa/general/0116.md b/ipa/general/0116.mdx similarity index 100% rename from ipa/general/0116.md rename to ipa/general/0116.mdx diff --git a/ipa/general/0117.md b/ipa/general/0117.mdx similarity index 98% rename from ipa/general/0117.md rename to ipa/general/0117.mdx index 25aea2b..4d1acc3 100644 --- a/ipa/general/0117.md +++ b/ipa/general/0117.mdx @@ -50,7 +50,7 @@ will promote clarity, completeness and consistency. > contains your projects. - When the same property appears in multiple polymorphic variants unified by - `oneOf` with a discriminator (see [IPA-125](0125.md)), that property's + `oneOf` with a discriminator (see [IPA-125](0125.mdx)), that property's description **should** be identical across variants. Variant-specific context **should** be documented in the variant schema's own `description`, not by diverging the property's description between variants. @@ -163,7 +163,7 @@ Operation summaries are titles describing an API operation. - API Producers **must not** use "Return All" unless the API can really return _all_ items in a collection - Collections may contain an unbounded number of entries and must be - paginated (see [Pagination](0110.md)). If the total number of entries can + paginated (see [Pagination](0110.mdx)). If the total number of entries can exceed the page size and prevent the client from accessing the full set, do not use "all." - API Producers **must** use only one main action verb e.g. "Create," "Update," diff --git a/ipa/general/0118.md b/ipa/general/0118.mdx similarity index 92% rename from ipa/general/0118.md rename to ipa/general/0118.mdx index 122b13c..a0c9883 100644 --- a/ipa/general/0118.md +++ b/ipa/general/0118.mdx @@ -20,4 +20,4 @@ conservatively reduces the potential of unintended impact. ## Further reading -- [IPA-119: Multi-Cloud Support by Default](0119.md) +- [IPA-119: Multi-Cloud Support by Default](0119.mdx) diff --git a/ipa/general/0119.md b/ipa/general/0119.mdx similarity index 100% rename from ipa/general/0119.md rename to ipa/general/0119.mdx diff --git a/ipa/general/0120.md b/ipa/general/0120.mdx similarity index 91% rename from ipa/general/0120.md rename to ipa/general/0120.mdx index a317279..7b7d7fe 100644 --- a/ipa/general/0120.md +++ b/ipa/general/0120.mdx @@ -16,7 +16,7 @@ documentation for MongoDB. - API producers **should** consider whether their changes warrant a new version or can be made backward compatible - API producers **should** refer to backwards compatibility - ([IPA-116](0116.md)) prior to versioning their API + ([IPA-116](0116.mdx)) prior to versioning their API - API producers **should not** version their API if the desired functionality can be achieved in a backwards compatible fashion - API producers **should** consider whether introducing a new endpoint @@ -30,4 +30,4 @@ documentation for MongoDB. ## Further Reading -- [IPA-116: Backwards compatibility](0116.md) +- [IPA-116: Backwards compatibility](0116.mdx) diff --git a/ipa/general/0121.md b/ipa/general/0121.mdx similarity index 100% rename from ipa/general/0121.md rename to ipa/general/0121.mdx diff --git a/ipa/general/0122.md b/ipa/general/0122.mdx similarity index 100% rename from ipa/general/0122.md rename to ipa/general/0122.mdx diff --git a/ipa/general/0123.md b/ipa/general/0123.mdx similarity index 97% rename from ipa/general/0123.md rename to ipa/general/0123.mdx index 85c02f3..30da41b 100644 --- a/ipa/general/0123.md +++ b/ipa/general/0123.mdx @@ -25,7 +25,7 @@ the expectation for that data field. - If so, API producers **must** document the allowable values. - The API **must not** accept invalid enum values and silently modify them to make them valid. Instead, the API should return a validation error (see - [Validation Errors](0114.md#validation-errors)) + [Validation Errors](0114.mdx#validation-errors)) - For example, accepting the client-provided value `open` but returning the value `OPEN` diff --git a/ipa/general/0124.md b/ipa/general/0124.mdx similarity index 76% rename from ipa/general/0124.md rename to ipa/general/0124.mdx index efa0202..f7c6f16 100644 --- a/ipa/general/0124.md +++ b/ipa/general/0124.mdx @@ -17,7 +17,7 @@ reduced when clients need to modify the lists. - A good rule of thumb is 100 elements - If repeated data has the chance of being too large, the API **should** use a sub-resource instead -- [Client-owned](0111.md#single-owner-fields) repeated fields **should** be +- [Client-owned](0111.mdx#single-owner-fields) repeated fields **should** be respected by the server - The server **should not** modify the order of elements or remove duplicates, without explicit documentation that the server will do so @@ -26,17 +26,17 @@ reduced when clients need to modify the lists. - A resource **may** use one of two strategies to enable updating a repeated field: - - Direct update using the standard [Update](0107.md) method + - Direct update using the standard [Update](0107.mdx) method - A standard `Update` method is only able to update the entire list - Custom `Add` and `Remove` methods - - When choosing a [custom method](0109.md) approach, API consumers **must - not** be able to set the field via [Create](0106.md) or [Update](0107.md) - operations + - When choosing a [custom method](0109.mdx) approach, API consumers **must + not** be able to set the field via [Create](0106.mdx) or + [Update](0107.mdx) operations :::note -Declarative-friendly resources **must** use the standard [Update](0107.md) +Declarative-friendly resources **must** use the standard [Update](0107.mdx) method, and not introduce `Add` and `Remove` methods. To learn more, see -[IPA-127](0127.md). +[IPA-127](0127.mdx). ::: diff --git a/ipa/general/0125.md b/ipa/general/0125.mdx similarity index 100% rename from ipa/general/0125.md rename to ipa/general/0125.mdx diff --git a/ipa/general/0126.md b/ipa/general/0126.mdx similarity index 100% rename from ipa/general/0126.md rename to ipa/general/0126.mdx diff --git a/ipa/general/0127.md b/ipa/general/0127.mdx similarity index 81% rename from ipa/general/0127.md rename to ipa/general/0127.mdx index 81619d6..4fec05e 100644 --- a/ipa/general/0127.md +++ b/ipa/general/0127.mdx @@ -29,12 +29,12 @@ require extra, stricter guidance to support IaC tooling automation. ## Guidance - A resource **must** be strongly consistent with the **Resource-Oriented - Design** ([IPA-101](0101.md)) + Design** ([IPA-101](0101.mdx)) - A resource **must** have `CREATE`, `DELETE`, `GET`, `LIST` methods, except for - [singleton resources](0113.md) and - [read-only resources](0101.md#read-only-resources) which **must** have `GET` + [singleton resources](0113.mdx) and + [read-only resources](0101.mdx#read-only-resources) which **must** have `GET` and `LIST` methods. -- A resource **should not** have custom methods ([IPA-109](0109.md)). Any +- A resource **should not** have custom methods ([IPA-109](0109.mdx)). Any complementary functionality of a resource exposed through custom methods will not be supported through automation. Deviation from this guidance requires a strong justification and review by the governing API body. @@ -55,12 +55,12 @@ error-prone development. ### Further Reading -- [IPA-101: Resource-Oriented Design](0101.md) -- [IPA-104: Get](0104.md) -- [IPA-105: List](0105.md) -- [IPA-106: Create](0106.md) -- [IPA-108: Delete](0108.md) -- [IPA-109: Custom Methods](0109.md) -- [IPA-111: Server-Modified Values and Defaults](0111.md) -- [IPA-114: Errors](0114.md) -- [IPA-125: Single Type in Request and Response](0125.md) +- [IPA-101: Resource-Oriented Design](0101.mdx) +- [IPA-104: Get](0104.mdx) +- [IPA-105: List](0105.mdx) +- [IPA-106: Create](0106.mdx) +- [IPA-108: Delete](0108.mdx) +- [IPA-109: Custom Methods](0109.mdx) +- [IPA-111: Server-Modified Values and Defaults](0111.mdx) +- [IPA-114: Errors](0114.mdx) +- [IPA-125: Single Type in Request and Response](0125.mdx) diff --git a/ipa/general/0128.md b/ipa/general/0128.mdx similarity index 92% rename from ipa/general/0128.md rename to ipa/general/0128.mdx index f6872ab..baa1762 100644 --- a/ipa/general/0128.md +++ b/ipa/general/0128.mdx @@ -19,7 +19,7 @@ expect when integrating or depending on a given API. - A **preview** API resource undergoes rapid iteration based on users' feedback. - The API resource **may** be available only to a selected groups of users. - The API resource **may** introduce breaking changes without requiring a new - version ([IPA-120](0120.md)). + version ([IPA-120](0120.mdx)). - API producers **must** establish a feedback mechanism for users to report issues and suggest improvements. - Consumers **must not** have any expectation of stability. @@ -27,9 +27,9 @@ expect when integrating or depending on a given API. - A **stable** API resource is a production-ready and fully supported API. - The API resource **must** be available for all users. - The API resource **must not** introduce breaking changes without requiring a - new version ([IPA-120](0120.md)). + new version ([IPA-120](0120.mdx)). - The API resource **must** release backwards compatibility - ([IPA-116](0116.md)) to ensure ongoing reliability. + ([IPA-116](0116.mdx)) to ensure ongoing reliability. - The API resource **must** remain supported until all users migrated to alternative versions, or until agreed between API provider and customers. - A **deprecated** API resource is still supported but **must** transition to @@ -51,7 +51,7 @@ expect when integrating or depending on a given API. ## Further Reading -- [IPA-116: Backwards Compatibility](0116.md) -- [IPA-120: Versioning](0120.md) +- [IPA-116: Backwards Compatibility](0116.mdx) +- [IPA-120: Versioning](0120.mdx) - [RFC 9745](https://datatracker.ietf.org/doc/rfc9745/) - [RFC 8594](https://datatracker.ietf.org/doc/html/rfc8594) diff --git a/ipa/general/0129.md b/ipa/general/0129.mdx similarity index 80% rename from ipa/general/0129.md rename to ipa/general/0129.mdx index 866b1c0..8eb0cc9 100644 --- a/ipa/general/0129.md +++ b/ipa/general/0129.mdx @@ -16,12 +16,12 @@ specified way. - API Producers **may** use query parameters for: - Filtering - Searching - - [Pagination](0110.md) - - [The envelope object](0115.md) - - [Cascading delete](0108.md#cascading-delete) + - [Pagination](0110.mdx) + - [The envelope object](0115.mdx) + - [Cascading delete](0108.mdx#cascading-delete) - Query parameters **must not** be used in place of request body fields for - [Create](0106.md) and [Update](0107.md) Methods, i.e. when the value causes a - side-effect + [Create](0106.mdx) and [Update](0107.mdx) Methods, i.e. when the value causes + a side-effect - Query parameters **must not** be required - API Producers **should** document the possible length of query parameter values @@ -73,18 +73,18 @@ values. - Filtering **should** be implemented using query parameters - For example, `/groups?name=project1` - Filtering and searching **may** be implemented for - - [List Methods](0105.md) - - [Custom Methods](0109.md) used for retrieving data + - [List Methods](0105.mdx) + - [Custom Methods](0109.mdx) used for retrieving data - Filtering and searching **must not** be implemented for - - [Get Methods](0104.md) - - [Create Methods](0106.md) - - [Update Methods](0107.md) - - [Delete Methods](0108.md) + - [Get Methods](0104.mdx) + - [Create Methods](0106.mdx) + - [Update Methods](0107.mdx) + - [Delete Methods](0108.mdx) ## Further Reading - [IETF RFC3986 - 3.4](https://www.ietf.org/rfc/rfc3986.txt) -- [IPA-108: Delete - Cascading Delete](0108.md#cascading-delete) -- [IPA-110: Pagination](0110.md) -- [IPA-115: Envelope Object](0115.md) -- [IPA-116: Backwards Compatibility](0116.md) +- [IPA-108: Delete - Cascading Delete](0108.mdx#cascading-delete) +- [IPA-110: Pagination](0110.mdx) +- [IPA-115: Envelope Object](0115.mdx) +- [IPA-116: Backwards Compatibility](0116.mdx) diff --git a/ipa/general/0130.md b/ipa/general/0130.mdx similarity index 100% rename from ipa/general/0130.md rename to ipa/general/0130.mdx diff --git a/ipa/index.md b/ipa/index.mdx similarity index 100% rename from ipa/index.md rename to ipa/index.mdx diff --git a/ipa/sdks/0900.md b/ipa/sdks/0900.mdx similarity index 100% rename from ipa/sdks/0900.md rename to ipa/sdks/0900.mdx