All, or almost all, APIs share the same structure.
List responses
Responses that return lists follow the same concept, they all return the same structure.
{
"count": 5,
"items": [/* data */],
"lastKey": "string", // returned ONLY when there are more results
"scrollId": "string" // returned ONLY on custom tables search result pagination
}
Response formatting
Some API endpoints allow for response transformation, or formatting.
So if you think our API responses are too verbose, complex or just plain ugly, feel free to make it better!
Just pass a JSONata expression in a vl-response-transformation header with your request to enable.
JSONata is used extensively within Vince Live, please read more in the section
Use cases
This gives the caller the freedom to determine the output format, which can be very handy in cases such as
- coding or transforming on the client side might limited or impossible,
- when you want to limit which fields or rename properties that should be returned,
- filtering irrelevant records (see note below),
- performing calculations, aggregations or grouping of data
- sorting list records
Note! All transformation occurs on the data returned from the API endpoint, *after* it has been fetched from the source. Pagination and/or result counts might not be correct if used for filtering in a partial or paginated response.
Concept
Usage
In your request, pass the header `vl-response-transformation` with a valid JSONata expression string as value.
Examples
Sorting records
vl-response-transformation: { "count": count, "items": items^(firstName, lastName) }
// before transformation
{
"count": 4,
"items": [
{ "firstName": "Zlatan", "lastName": "Aarto", "email": "a@x.com" },
{ "firstName": "Melody", "lastName": "Mobile", "email": "melody.mobile@x.com" },
{ "firstName": "Aage", "lastName": "Zlibrahimovic", "email": "aage@x.com" },
{ "firstName": "Aage", "lastName": "Aamodt", "email": "aage2@x.com" }
]
}
// after transformation
{
"count": 4,
"items": [
{ "firstName": "Aage", "lastName": "Aamodt", "email": "aage2@x.com" },
{ "firstName": "Aage", "lastName": "Zlibrahimovic", "email": "aage@x.com" },
{ "firstName": "Melody", "lastName": "Mobile", "email": "melody.mobile@x.com" },
{ "firstName": "Zlatan", "lastName": "Aarto", "email": "a@x.com" }
]
}
Output without any formatting
GET /v1/custom-tables/search/my-products?q=*test*
// raw response
{
"count": 4,
"items": [
{
"product": "Prod-222",
"description": "A test product",
"status": "Active",
"price": 100
},
{
"product": "Prod-333",
"description": "A test product",
"status": "OutOfStock",
"price": 250
},
{
"product": "Prod-111",
"description": "A test product",
"status": "Active",
"price": 50
},
{
"product": "Prod-123",
"description": "A test product",
"status": "Active",
"price": 500
}
]
}
Selecting and renaming properties
vl-response-transformation: items.{ "item": product, "price": price }
formatted response
[
{
"item": "Prod-222",
"price": 100
},
{
"item": "Prod-333",
"price": 250
},
{
"item": "Prod-111",
"price": 50
},
{
"item": "Prod-123",
"price": 500
}
]
Grouping
vl-response-transformation: items{ "Active": $[status="Active"].product[], "OutOfStock": $[status="OutOfStock"].product[] }
// response
{
"Active": [
"Prod-222",
"Prod-111",
"Prod-123"
],
"OutOfStock": [
"Prod-333"
]
}
Filtering and specific properties
vl-response-transformation: items[status="OutOfStock"].{ "item": product, "price": price }[]
// response
[
{
"item": "Prod-333",
"price": 250
}
]
Sum of all prices
vl-response-transformation: $sum(items.price)
// response
900
Renaming and ignoring properties
GET https://0/workflows
vl-response-transformation: {"count": $count(items), "lastKey": lastKey, "items": items.{ "active": active, "name": workflowName, "alias": workflowAlias }}
// output in screenshot below
Error handling
If the input JSONata expression is invalid, it will be ignored and the raw response will be returned.
Limitations
The total request header including URL can not exceed 10kb.
Response size (before or after transformation) can not exceed 6mb.
Supported API endpoints
Currently supported endpoints:
- `GET /v1/custom-tables/data` and subpaths
- `GET /v1/custom-tables/search/{tableName}`
- `POST /v1/custom-tables/search/{tableName}`
- `ANY /api-clients` and subpaths
- `ANY /connections` and subpaths
- `ANY /dashboards` and subpaths
- `ANY /environments` and subpaths
- `ANY /gateways` and subpaths
- `ANY /metadata` and subpaths
- `ANY /roles` and subpaths
- `ANY /tenant` and subpaths
- `ANY /users` and subpaths
- `ANY /workflows` and subpaths