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 primary action on the resource (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. The request body SHOULD conform to RFC 7386 - JSON Merge Patch.	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