Using POST vs GET to Query

Most of the APIs that support update operations will include the standard GET, PUT, PATCH, DELETE verbs and these are documented in the OpenAPI documentation.

The _query APIs and the raw APIs and strictly for querying data from Vitruvi and only supprt GET operations. However, these APIs also support field selection and filtering query paramaters that can include a lot of data and quickly exceed the generally supported URL length limit of 2048 characters.

For this reason, it is recommended that all calls to the _query and raw APIs use a modified POST call to retrieve data. The POST call allows the caller to place the query parameters into the body of the POST rather than in the URL.

To achieve this, 2 additional values need to be added to the header of the call:

X-HTTP-Method-Override:GET
Content-Type:application/x-www-form-urlencoded

Example using the RAW APIs

With this added to the header, this GET call:

curl --location --request GET 'https://my_workspace.api.vitruvi.cc/api/v1/raw/core/customfieldvalue?limit=10000&offset=0&modified__gt=2022-03-01T00:00:00Z&modified__lt=2022-03-31T00:00:00Z' \
--header 'Authorization: Bearer <<SANITIZED>>' \
--header 'Accept: application/json'

becomes this POST call:

curl --location --request POST 'https://my_workspace.api.vitruvi.cc/api/v1/raw/core/customfieldvalue' \
--header 'Authorization: Bearer <<SANITIZED>>' \
--header 'Accept: application/json' \
--header 'X-HTTP-Method-Override: GET' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'limit=10000' \
--data-urlencode 'offset=0' \
--data-urlencode 'modified__gt=2022-03-01T00:00:00Z' \
--data-urlencode 'modified__lt=2022-03-31T00:00:00Z'

Example using the _QUERY APIs

The same method can also be used on the _query APIs:

curl --location --request POST 'https://my_workspace.api.vitruvi.cc/api/v1/invoicing/invoices_query' \
--header 'Authorization: Bearer <<SANITIZED>>' \
--header 'Accept: application/json' \
--header 'X-HTTP-Method-Override: GET' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'limit=100' \
--data-urlencode 'offset=0' \
--data-urlencode '$filter=status in ('\''pending'\'','\''invoiced'\'') and ((modified gt '\''2021-02-01T00:00:00-03:00'\'' and modified lt '\''2021-04-01T00:00:00-03:00'\'') or (modified gt '\''2022-02-01T00:00:00-03:00'\'' and modified lt '\''2022-12-01T00:00:00-03:00'\'')) and not startswith(tolower(payee_name),'\''m'\'')'