Queries & Reports API: UpdateQuery

API endpoints for queries, reports, and record operations

UpdateQuery

Update an existing Query stored in the table.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Queries:Update.

URL Examples

https://api.catch-e.com/gb/queries/{query_id}

HTTP Method

Use the HTTP Method 'PUT' for consuming this web service.

Headers

Key	Format	Notes	Mandatory
Audit-User-Id	string	Pass a user_id here to create audit records with this user's details. This can only be done if the authenticated API user has Roles / Apis checked for the permission Audit:UserIdOverride	No

Body (JSON)

Example Value.

{ "name": "COUNT of contracts with Rego", "description": "Count of Active Contracts with Rego", "query": "SELECT COUNT(*) FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no != 'ORDER';", "super_flag": "no", "status_flag": "active"}

Queries are validated prior to being saved in the table.

(Successful) Output Example

Example response.

{ "query": "SELECT COUNT(*) FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no != 'ORDER';", "query_id": "100249", "name": "COUNT of contracts with Rego", "description": "Count of Active Contracts with Rego", "super_flag": "no", "max_execution_time": 300, "user_id_last_edit": "10937", "last_edit": "2023-12-05 10:47:53", "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/gb/queries/100249" } }, "_embedded": { "scheduler_jobs": [] }}

Response Details

Validation Messages	Comments
401 - Unauthorized

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 422 - Unprocessable Entity | | |

{ "warning_messages": { "fieldName": { "warningExceptionCode": "A textual description of the warning exception" } }, "validation_messages": { "fieldName": { "validationExceptionCode": "A textual description of the validation exception" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}

| Correct your request content before submitting your request again. |
| 429 - Too Many Requests | | |

"title": "To Many Requests"

| The rate limit of your system has been exceeded and the response contains the number of seconds you should wait until trying again. Your rates limit includes all legacy web services and current token-based APIs. Whitelisted IP Addresses are excluded, the whitelist includes the localhost IP so that internal APIs are excluded from rate limiting counts. Catch-e's rate limiting uses the sliding window concept. See the following discussion piece about this: https://blog.cloudflare.com/counting-things-a-lot-of-different-things/ |
| 500 - Unexpected error | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string"}

| This response could be a temporary outage or potentially a bug. If you are consistently receiving this error, please raise a ticket with your Account Manager. Please supply the complete Request & Response payloads. [Warning:] Please remember to NEVER send user login credentials when sending a ticket request. Catch-e staff have our own credentials we can use to de-bug these tickets. |

GetArchiveQueries

Get a history of Query changes for a Query stored in the table.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Queries:Get.

URL Examples

https://api.catch-e.com/gb/queries/archive

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

Parameters

Name	Format	Notes	Mandatory
Query
query_id	string	Query ID.	yes
page	number	Returns all pages by default. You can limit the results with this input value (default = 1).	no
page_size	number	25 results per page are returned by default. You can limit the results with this input value (default = 25).	no

(Successful) Output Example

Example response shown here displays three changes that have been made using updateQuery to Query ID 100249.

{ "_links": { "self": { "href": "https://api.test.catch-e.com/gb/queries/archive?query_id=100249&page=1&page_size=25" }, "first": { "href": "https://api.test.catch-e.com/gb/queries/archive?query_id=100249&page_size=25" }, "last": { "href": "https://api.test.catch-e.com/gb/queries/archive?query_id=100249&page=1&page_size=25" } }, "_embedded": { "archived_queries": [ { "query_archive_id": "11989979731563965186", "query_id": 100249, "data_sha": "3f5f9c679ff38f9fd7ed5f6f649df9ac208a7cb0", "query": "SELECT COUNT(contract_id) AS contract_count FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no != 'ORDER' LIMIT 20;", "last_edit": "2023-12-05 10:46:16", "user_id_last_edit": 10000, "_links": { "self": { "href": "https://api.test.catch-e.com/gb/queries/archive" } } }, { "query_archive_id": "11989979731563965187", "query_id": 100249, "data_sha": "3403ad86b7a842f5079f772b16526fe76e2b9b70", "query": "SELECT COUNT(*) FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no = 'ORDER';", "last_edit": "2023-12-05 10:47:53", "user_id_last_edit": 10000, "_links": { "self": { "href": "https://api.test.catch-e.com/gb/queries/archive" } } }, { "query_archive_id": "11989979731563965206", "query_id": 100249, "data_sha": "6d4764ce4e5493ba59704b566c7bc592a9620f81", "query": "SELECT COUNT(*) FROM fm_contracts WHERE suspend_date = '0000-00-00' AND reg_no != 'ORDER';", "last_edit": "2023-12-05 11:01:18", "user_id_last_edit": 10000, "_links": { "self": { "href": "https://api.test.catch-e.com/gb/queries/archive" } } } ] }, "page_count": 1, "page_size": 25, "total_items": 3, "page": 1}

Response Details

Validation Messages	Comments
401 - Unauthorized

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

{ "validation_messages": { "query_id": { "noRecordFound": "No record matching the input was found" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}

| Correct your request content before submitting your request again. |
| 429 - Too Many Requests | | |

"title": "To Many Requests"

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string"}

ExecuteReportWebService

This API allows you to run selected system reports available from the Fleet / Administration / Reports menu.

Supplementary SWAGGER documentation is available here: api.test.catch-e.com/docs/#/Web%20Services/executeReportWebService

Available Reports

For more information on the set up requirements, click on the link below of the report you wish to run via the API.

Accidents
Reg Renewals
Service Overdue

PrintQuery

Executes a Query stored in the table.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Queries:Print.

URL Examples

https://api.catch-e.com/gb/queries/print-query/{query_id}

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

Input Fields (Header)

The representational output format of the report query is controlled by HTTP Accept header. Three content types are presently supported:

text/csv
text/xml
application/json (default)

**Queries that run successfully but result in 0 rows will return an HTTP 204 (No content) response from the API.
**
Queries that run exceed the will return an HTTP 422 (Unprocessable Content) response from the API.

(Successful) Output Example

Returns content based on the Query you have selected. Example response.

[ { "contract_count": "1142" }]

Response Details

Validation Messages	Comments
401 - Unauthorized

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

{ "validation_messages": { "query_id": { "noRecordFound": "No record matching the input was found" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}

| Correct your request content before submitting your request again. | |

 "query_id": { "invalidQuery": "Query execution was interrupted, maximum statement execution time exceeded." }

"title": "To Many Requests"

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 599, "detail": "string"}