IPA-107: Update

In REST APIs, it is customary to make a PATCH or PUT request to a resource's URI (for example, /groups/{groupId}/clusters/{clusterName}) to update that resource.

Guidance

• APIs should provide an update method for resources unless it is not valuable for users to do so
  • Read-only resources must not have an Update method
  • 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
• The HTTP verb should be PATCH and support partial resource update
  • The HTTP verb may be PUT If the method will only ever support full resource replacement
  • 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
  • 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
  • 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)
  • 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 resource to match the request
    • Any fields not included in the request body must be unset or set to their default value(s)
  • If the client explicitly provides null for an optional field in the request, the server should unset the field or reset it to its default value
    • The server should return a validation error 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 must not cause
• The response status code should be 200 OK
  • If the request for a partial update is empty, the Update method should 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

Example

PATCH /groups/${groupId}/clusters/{clusterName}

Error Handling

See IPA-114: Errors for guidance on error handling and documentation.

Naming

• Operation ID must be unique
• Operation ID must be in camelCase
• Operation ID must start with the verb “update”
• 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, the last noun may be the plural form of the collection identifier

Examples:

Resource Identifier	Operation ID
/groups/${groupId}/clusters/${clusterName}	updateGroupCluster
(Singleton) /groups/${groupId}/settings	updateGroupSettings