Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions ipa/general/0101.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,21 @@ When designing an API, consider the following (roughly in logical order):
- Resources **may** have any number of sub-resources
- The schema for a resource **must** be the same across all methods related to
the resource
- The schema consistency rule implies that every field accepted in a request
body **must** also be present in the response body for the same resource.
Omitting request fields from responses breaks declarative clients and forces
manual reconciliation in downstream tooling.
- The only exceptions are [sensitive fields](0111.mdx#sensitive-fields), which
may be omitted entirely (write-only) or may appear only in the Create
response (reveal-once).
- For the per-method expression of this rule, see [Create](0106.mdx) and
[Update](0107.mdx).
- Resources declared by clients **must not** be silently removed by the server
as a result of time-based expiry, inactivity, or other server-side lifecycle
events. If such a lifecycle transition is part of the resource's domain model,
it **must** be represented as a terminal status on the resource (e.g.
`EXPIRED`, `REVOKED`, `REJECTED`), and the resource **must** remain readable
through the Get and List methods until the client explicitly deletes it.

:::warning[Important]

Expand Down
4 changes: 2 additions & 2 deletions ipa/general/0106.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ collection.
- A `Request` object **must** include only input fields
- 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.mdx) method
- The response body **must** be the same resource returned by the
[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
Expand Down
4 changes: 2 additions & 2 deletions ipa/general/0107.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,9 @@ resource.
- 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
- The response body **must** be the same resource returned by the
[Get method](0104.mdx)
- The Update method **should** return the complete resource to avoid
- The Update method **must** 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
Expand Down
11 changes: 7 additions & 4 deletions ipa/general/0108.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,13 @@ resource.
[204 No Content](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204)
status
- The request **must not** include a body
- 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.mdx)
- The Delete method **must** succeed if and only if a resource was present and
was successfully deleted.
- If the resource did not exist, the method **must** respond with a
`404 Not Found` error per [IPA-114](0114.mdx#not-found).
- The Delete method **must not** return a successful response while any internal

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we considering DELETE operations that act as a reset for singleton resources?

state of the resource — settings, policies, configurations, or any other state
without an independent endpoint — remains.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we clarify what without an independent endpoint means in the guidelines?


Example

Expand Down