IPA-104: Get

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

State

Adopt

Guidance

• APIs must provide a Get method for resources
• The purpose of the Get method is to return data from a single resource
• The HTTP verb must be GET
• The method must not cause side effects
• The request must not include a body
• API producers should implement as a Response suffixed object
  • A Response object must not include fields available only on creation or update
    • In OpenAPI, this means that the Response object must not include fields with writeOnly: true
• The response status code must be 200 OK
• The response may include a HATEOAS links field

Example

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

Naming

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

Examples:

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

Error Handling

See IPA-114: Errors for guidance on error handling and documentation, in particular Authentication, Authorization and Not Found.