Service Responses
Service Responses
Service Responses
When an API is invoked, the API MUST provide a response to the request. Depending on the verb being used, the response MAY include a response body.
The following sections provide information and context regarding status codes, verbs, and general behavior that services SHOULD leverage when providing responses to requests.
Successful Responses (2xx)
Successful responses are those where the service has fulfilled the request. Service responses MUST correspond to the behavior considered proper for a service responding to such a request.
| Request Verb | Request Description/Content | Response Code | Response Behavior |
|---|---|---|---|
| GET | Requests a resource, using information in the URL to provide context and filtering | 200 ”OK” | The service MUST return the resource(s) that corresponds to the request |
| GET | Requests a resource, using information in the URL to provide context and filtering | 206 ”Partial Content” | The service MUST return the partial content that is available, and MUST provide range information for the requester for acquiring the rest of the resource. For the requester to get a valid resource, it MUST continue to query for additional content until the complete resource is fully downloaded. 206 MUST NOT be used when the response is just a subset of a larger set of paginated data (see Pagination / Continuation). In these cases, retrieving more records is optional. The service MUST include Content-Type and Content-Range headers in its response.Valid example: ../users/{userId}/profileImage that returns only the first part of the image. The returned data would not be a valid image without additional requests to retrieve the rest of the image. |
| POST (create) | Provides the representation of the resource being created | 201 ”Created” | If the service has synchronously created a new resource, the service returns 201 and a full representation of the new resource. If the service also returns the URI of the created resource in the HTTP header, it MUST return the URI in the HTTP Location header field. APIs MAY implement mechanisms that allow returning a subset of the full representation (e.g. $select oData System Query option), but the default response MUST be the full representation of the new resource. |
| POST (create) | Provides the representation of the resource being created | 202 ”Accepted” | If the service will create the resource asynchronously , the service returns a 202 along with a “task” reference (likely TRN; actual format TBD) that contains information that the client can use to get the status of the resource being created. It MUST be noted clearly in the API endpoint documentation if the client needs to anticipate receiving 202 responses. Please send a note to api-standard-ug@trimble.com if you need to implement asynchronous resource creation so that a standard “task” block and API can be created. |
| POST (search) | 200 ”OK” | The body of the response contains the results of the search | |
| PUT | Provides the updated resource representation that SHOULD update an extant resource, or MUST facilitate the creation of a new resource | 200 ”OK” | This code is returned if the resource already existed and was replaced. |
| PUT | Provides the updated resource representation that SHOULD update an extant resource, or MUST facilitate the creation of a new resource | 201 ”Created” | Same as POST - 201 “Created” |
| PUT | Provides the updated resource representation that SHOULD update an extant resource, or MUST facilitate the creation of a new resource | 202 ”Accepted” | Same as POST - 202 “Accepted” |
| PATCH | Provides the partial updates for the target resource | 200 ”OK” | The service MUST return the full resource representation. If any part of the PATCH update fails, the service MUST return an appropriate error code and MUST NOT modify the original resource. |
| PATCH | Provides the partial updates for the target resource | 202 ”Accepted” | See POST - 202 “Accepted” for more information on successful handling. See PATCH - 200 “OK” for how to handle the failure of any update. |
| DELETE | Deletes the specified resource. MUST not permit bulk or mass deletes. | 204 ”No Content” | The service MUST NOT return a body |
Client Error Responses (4xx)
Client errors are generated when the requester does something wrong, such as submitting an improperly formatted request or trying to access a resource that does not exist. All client error responses MUST return an error document conforming to the Standard Error Payload.
| Verb | Error Condition | Response Code | Response Behavior |
|---|---|---|---|
| ANY | The request contains malformed syntax and cannot be understood by the server | 400 ”Bad Request” | The service MUST return a response body with a clear, unambiguous description of the error and at least one suggestion for how to correct the error. |
| ANY | The request lacks valid authentication credentials that the service requires | 401 ”Unauthorized” | The service MUST NOT return any information that can be used to compromise credentials or identities. |
| ANY | The request is valid and acceptable to the service, but it is refusing to fulfill the request. This could be due to an authentication or authorization issue or attempting to execute a prohibited action | 403 ”Forbidden” | The service MUST NOT return any information that can be used to compromise credentials or identities. |
| GET | The requested resource was not found. (see “Use of Status Code 404 - Not Found”) | 404 ”Not Found” | The service MUST return a response body with a clear, unambiguous description of the error and at least one suggestion for how to correct the error. |
| DELETE PATCH | The resource specified was not found. | 404 ”Not Found” | The service MUST NOT return a resource representation. |
| ANY | The verb specified is not applicable for the requested resource | 405 ”Method Not Allowed” | The service MUST return a response body with a clear, unambiguous description of the error and at least one suggestion for how to correct the error. |
| GET PUT PATCH POST | The request specified an Accept header value that cannot be fulfilled by the service | 406 ”Not Acceptable” | The service MUST return an informative message in the response body that indicates which formats are acceptable. |
| ANY | The request cannot be fulfilled due to the current state of the resource | 409 ”Conflict” | The service MUST return information related to the nature of the conflict. |
Use of Status Code 404 - Not Found
HTTP response code 404 MUST be returned when the specified resource cannot be located..
When an empty but extant collection is retrieved on a GET or POST to search and/or filter the collection, a 200 - “OK” status code MUST be returned along with an empty array. This is because the resource actually was found (the collection) but was empty.
Below are examples of things not found and the appropriate HTTP response codes:
| Operation | Condition | Response |
|---|---|---|
GET .../things/123 | ”Thing” with the ID “123” was previously deleted or never existed | 404 |
GET .../toys | There is no collection called “toys” | 404 |
GET .../toys | There is a collection called “toys” but it’s empty | Empty Array200 |
GET .../toys?type=robot | There is a collection called “toys” and there are toys in it but there are no robots. | Empty Array200 |
Server Error Responses (5xx)
Server errors are generated when server-side processing of a request fails for any reason.
| Verb | Error Condition | Response Code | Response Behavior |
|---|---|---|---|
| ANY | Internal Server Error | 500 | The service MUST return a response body with a clear, unambiguous description of the error and at least one suggestion for how to correct the error. |
| ANY | Gateway Timeout | 504 | The service MUST NOT return any information that can be used to compromise credentials or identities. |
5xx error responses MUST return an error document conforming to the Standard Error Payload. 5xx error responses MUST further specify ways for the client to take an actionable next step such as linking to a support ticket page for the service or identifying how to contact support.