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.

State

Adopt

Guidance

• APIs should provide an update method for resources unless it is not valuable for users to do so
  • 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
• 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
• 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