chore(ipa): Rename guideline docs from .md to .mdx

ipa/general/0003.md → 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

ipa/general/0004.md → 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.

ipa/general/0101.md → 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

ipa/general/0103.md → 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
 

ipa/general/0104.md → 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.

ipa/general/0105.md → 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)

ipa/general/0106.md → 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
 

ipa/general/0107.md → 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:
 

ipa/general/0108.md → 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
 

ipa/general/0109.md → 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

ipa/general/0111.md → 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).
 
 :::