diff --git a/ipa/general/0127.mdx b/ipa/general/0127.mdx index 4fec05e..45dedcb 100644 --- a/ipa/general/0127.mdx +++ b/ipa/general/0127.mdx @@ -28,16 +28,297 @@ require extra, stricter guidance to support IaC tooling automation. ## Guidance -- A resource **must** be strongly consistent with the **Resource-Oriented - Design** ([IPA-101](0101.mdx)) -- A resource **must** have `CREATE`, `DELETE`, `GET`, `LIST` methods, except for - [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.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. + + + + +A resource **must** be strongly consistent with the **Resource-Oriented Design** +([IPA-101](0101.mdx)). + + + + + +```yaml +paths: + /projects: + get: + operationId: listProjects + post: + operationId: createProject + /projects/{projectId}: + get: + operationId: getProject + delete: + operationId: deleteProject +``` + + + Paths form a noun hierarchy and each verb maps to a standard method on the + resource, so the resource can be expressed as a desired state rather than a + sequence of actions. + + + + + + +```yaml +paths: + /createProject: + post: + operationId: createProject + /deleteProjectById: + post: + operationId: deleteProjectById +``` + + + The paths name actions instead of a resource. An action-shaped interface + cannot be reconciled to a desired state, which is what IaC tooling depends on. + + + + + + + Enumerate every entry under `paths` and group the paths by their resource + segment. + + + Confirm each path alternates collection nouns and resource identifiers + rather than encoding a verb or action. + + + Confirm each operation maps to a standard method on its resource (the verb + matches the resource semantics, not an arbitrary RPC). + + + Report any path or operation that models an action instead of a resource as + a deviation from Resource-Oriented Design. + + + + + + + + + +A resource **must** have `CREATE`, `DELETE`, `GET`, and `LIST` methods. + + + + + +```yaml +paths: + /orders: + get: + operationId: listOrders + post: + operationId: createOrder + /orders/{orderId}: + get: + operationId: getOrder + delete: + operationId: deleteOrder +``` + + + The collection exposes `LIST` and `CREATE` and the item exposes `GET` and + `DELETE`, so the full lifecycle of the resource can be driven declaratively. + + + + + + +```yaml +paths: + /orders: + post: + operationId: createOrder + /orders/{orderId}: + get: + operationId: getOrder +``` + + + `LIST` and `DELETE` are missing. Without `LIST`, an IaC tool cannot discover + existing resources to reconcile; without `DELETE`, removed configuration + cannot be applied. + + + + + + + Group the paths by resource: a collection path and its corresponding item + path with a path parameter. + + + For each resource, collect the operations on the collection path (`get` for + `LIST`, `post` for `CREATE`) and on the item path (`get` for `GET`, `delete` + for `DELETE`). + + + Confirm all four standard methods are present for the resource. + + + Report any resource that is missing one or more of `CREATE`, `DELETE`, + `GET`, or `LIST`, unless it qualifies as a singleton or read-only resource. + + + + + + + + + +[Singleton resources](0113.mdx) and +[read-only resources](0101.mdx#read-only-resources) **must** have `GET` and +`LIST` methods. + + + + + +```yaml +paths: + /audit-events: + get: + operationId: listAuditEvents + /audit-events/{eventId}: + get: + operationId: getAuditEvent +``` + + + Audit events are read-only, so the resource correctly exposes only `GET` and + `LIST` and omits the mutating methods that do not apply. + + + + + + +```yaml +paths: + /audit-events: + post: + operationId: createAuditEvent + /audit-events/{eventId}: + delete: + operationId: deleteAuditEvent +``` + + + A read-only resource exposes mutating methods and omits `GET` and `LIST`. The + required read methods are absent, and the mutating methods imply a lifecycle + the resource does not have. + + + + + + + Identify resources that are singletons (no collection path with a list + operation, accessed at a fixed path) or read-only (state is server-owned and + not client-mutable). + + + For each such resource, confirm a `GET` method is present (`get` on the item + path) and a `LIST` method is present (`get` on the collection path). + + + Confirm no mutating methods (`CREATE`, `DELETE`) are exposed where the + resource cannot be created or removed by the client. + + + Report any singleton or read-only resource that is missing `GET` or `LIST`. + + + + + + + + + +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. + + + + + +```yaml +paths: + /jobs: + post: + operationId: createJob + /jobs/{jobId}: + get: + operationId: getJob + patch: + operationId: updateJob +``` + + + State that would otherwise be set by a custom action is modeled as a standard + update, so the resource can be reconciled to a desired state by an IaC tool. + + + + + + +```yaml +paths: + /jobs/{jobId}: + get: + operationId: getJob + "/jobs/{jobId}:cancel": + post: + operationId: cancelJob +``` + + + `cancel` is a custom method expressing an action rather than a state. IaC + tooling cannot represent invoking an action, so this behavior falls outside + automation. + + + + + + + Enumerate the operations under `paths` and identify any custom methods, such + as a path segment of the form `:verb` or an operation that does not map to a + standard `CREATE`, `READ`, `UPDATE`, `DELETE`, or `LIST` method. + + + For each custom method, determine whether the same outcome could be + expressed as a state change on a standard method (for example, a status + field updated via `PATCH`). + + + Flag every custom method on a resource. Each occurrence is a deviation that + requires explicit justification and review by the governing API body. + + + + + + + + ### Motivation and Strategic Goals