Except for the overview section of the documentation, the remaining API documentation is centered around the resources exposed in the API and how to access and modify those resources.
Most resources support the following methods:
Additionally, some endpoints support the following methods:
Some API resources support other methods for retrieving reports, downloading resources, executing functions, etc. as documented in the APIs for those resources.
Per RFC 2731 Section 4.3.4: “The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.” This is the pattern followed by the API and, therefore, care must be taken that any PUT operation contains the entire object to be saved in the message payload.
Attempts to update a few properties via a PUT operation that only contains the properties that are to be updated will not result in the other properties not defined in the payload being left as-is. The properties excluded from the PUT message payload are replaced with blank or null values since the target of the PUT is “replaced with the state defined by the representation enclosed in the request message payload”. This will result in data loss. To avoid data loss the current representation of the object should be retrieved with a GET operation and then updated with new values for any properties that changed and then that complete object can be updated via a PUT.
Certain APIs may have endpoints for MERGE and/or PATCH functionality which can be used to modify a partial resource.
The API uses a custom http verb MERGE. For updating a resource based on a partial resource object. If custom http verbs are not supported by your http client use a POST with the X-HTTP-Method-Override http header set to MERGE in order to instruct the API that you are doing a merge.
Note that it is not possible to merge deep object properties individually. This means, for example, that it is not possible to set InvoiceLineItem.Invoice.DueDate as the entire Invoice object would be replaced. If deep value changes are needed then either GET the current object, update the needed properties, and do a PUT of the whole object or use the PATCH method.