HTTP Verbs
HTTP Verbs
HTTP Verbs
Access to resources MUST be done using the appropriate HTTP Verb. HTTP verbs MUST be used in compliance with their definitions under the HTTP standard. The action taken on the representation will be contextual to the media type being worked on and its current state.
Usage of the verb MUST correspond to the desired action (e.g. DELETE for removing a resource).
One notable and oft used exception is using POST in what is essentially a GET situation because of URL length restrictions or due to the complexity of the filtering specification. See Searching and Filtering for details.
The following table shows standard HTTP verbs followed by Trimble’s standards for the behavior and use of each verb.
| Verb | Purpose | Description | Idempotent |
|---|---|---|---|
| POST | Create | Create a new resource within the specified collection. POSTing an extant resource MUST generate an error. The request MUST contain a body that is the resource to be created. | Potentially |
| POST | Search | Search a collection - The body of the POST is the specification for the search. See Filtering Using a Service-Specific Query Payload for the details of the search method and body. | Yes |
| PUT | Replace | Update an existing resource by replacing it with a complete instance. PUT SHOULD be used in cases where the resource is not intended to be editable, like an image or a file. PUT SHOULD NOT be used in situations where a resource is being edited. PATCH SHOULD be used in these cases. The request MUST contain a body that is the complete representation of the resource. | Yes |
| PATCH | Update | Update an existing resource by replacing some of its properties. | Potentially |
| GET | Retrieve | Retrieve a resource or resources specified in the URL. The request MUST NOT require a body | Yes |
| DELETE | Delete | Delete the single resource specified in the URL. The request MUST NOT require a body | Yes |
POST and complex search actions
The one exception to standard usage of HTTP verbs is using POST for resource searching and filtering. This exception is in place due to URL length restrictions or filtering specification complexity. POST endpoints for this use case MUST meet the following criteria:
- Endpoint MUST expose only search functionality with filtering
- Endpoint MUST end in /searches
- Endpoint MUST NOT modify data