Skip to main content

IPA-113: Singleton Resources

An API may define singleton resources. A singleton resource must always exist by virtue of the existence of its parent, with one and exactly one per parent.

State

Adopt

Guidance​

  • Singleton resources must not have a user-provided or system-generated ID
  • Singleton resources must not define the Create or Delete standard methods
    • The singleton is implicitly created or deleted when its parent is created or deleted
  • Singleton resources must define the Get method
  • Singleton resources should define the Update method, unless the resource is read-only
  • Singleton resources may define custom methods as appropriate

Example

GET /groups/${groupId}/settings
###
PATCH /groups/${groupId}/settings

Read-Only Singleton Resources​

Read-only singleton resources are singleton resources that cannot be modified by API consumers.

  • Read-only singleton resources must have only the Get method
  • Read-only singleton resources must not have Create, Update, or Delete methods
  • Read-only singleton resources may have custom methods 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
  • Unsupported operations on read-only singleton resources should return 405 Not Allowed
  • Unsupported operations must not be documented

Resetting Singleton Resources​

Singleton resources can be restored to their default state without deleting the parent resource. For such cases, a :reset custom method must be used.

  • The :reset custom method name must be reserved exclusively for restoring singleton resources to their default state
  • The :reset custom method must use the POST HTTP method
  • The :reset custom method must be idempotent
    • Calling reset multiple times must produce the same result as calling it once
  • The :reset custom method must return a 200 OK response with the reset resource in the response body
  • The :reset custom method must not have a request body
  • Read-only singleton resources must not define a :reset custom method
    • Read-only singleton resources cannot be modified, so reset is not applicable