IPA-106: Create

In REST APIs, it is customary to make a POST request to a collection's URI (for example, /groups/{groupId}/clusters) to create a new resource within that collection.

State

Adopt

Guidance

• APIs should provide a create method for resources unless it is not valuable for users to do so
  • The purpose of the create method is to create a new resource in a collection
• The HTTP verb must be POST
• The resource must be the request body
  • API producers should implement as a Request suffixed object
    • 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 method
• Create 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 must be 201 Created

Example

POST /groups/${groupId}/clusters

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 “create”
• 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

Examples:

Resource Identifier	Operation ID
/groups/${groupId}/clusters	createGroupCluster