Skip to main content

Common Features

All, or almost all, Vince Platform APIs share the same structure and conventions. This page documents behavior that's common across endpoints, instead of repeating it on every individual API reference page.

Response formatting​

Some API endpoints let you transform, or reformat, their response before it reaches you.

If the default response is too verbose, too complex, or just not shaped the way you need it, you can reshape it yourself: pass a JSONata expression in a vl-response-transformation header with your request.

tip

JSONata is used extensively within Vince Platform — see the Transform component for another place it shows up, and the JSONata exerciser to experiment with expressions against sample data.

Concept​

Flow diagram: a client sends a request to an API endpoint, which is handled by a handler that fetches data from a data source. The raw response is checked for a transform header — if absent, the raw response goes back to the client; if present, it is passed through a transformation step first, and the transformed response is returned instead.

When a request reaches the endpoint, the handler fetches data from its normal source as usual. Before the response is returned, the handler checks for a vl-response-transformation header:

  • If it's absent, the raw response is returned unchanged.
  • If it's present, the raw response is passed through your JSONata expression first, and the transformed result is what you receive.

Use cases​

This gives the caller freedom to determine the output shape, which is useful when:

  • Coding or transforming the response on the client side is limited or impossible
  • You want to limit which fields are returned, or rename properties
  • You want to filter out irrelevant records (see note below)
  • You need to perform calculations, aggregations, or grouping
  • You want to sort list records
note

Transformation happens on the data already returned by the endpoint, after it has been fetched from the source. Pagination and result counts are calculated before transformation — so filtering out records in the transformation does not reduce the reported count or affect pagination.

Usage​

Add a vl-response-transformation header to your request, with a valid JSONata expression as its value.

Examples​

The examples below all transform the same sample response — a list of products:

[
  { "id": 101, "name": "Steel Bracket", "category": "Hardware", "price": 12.5, "inStock": true, "internalRef": "WH-001", "createdAt": "2024-01-15" },
  { "id": 102, "name": "Copper Pipe", "category": "Plumbing", "price": 8.75, "inStock": true, "internalRef": "WH-014", "createdAt": "2024-02-03" },
  { "id": 103, "name": "Wood Screw", "category": "Hardware", "price": 0.15, "inStock": false, "internalRef": "WH-022", "createdAt": "2023-11-30" },
  { "id": 104, "name": "PVC Fitting", "category": "Plumbing", "price": 3.2, "inStock": true, "internalRef": "WH-009", "createdAt": "2024-03-10" }
]

Selecting and renaming properties​

vl-response-transformation:

$.{"sku": id, "productName": name}

Result:

[
  { "sku": 101, "productName": "Steel Bracket" },
  { "sku": 102, "productName": "Copper Pipe" },
  { "sku": 103, "productName": "Wood Screw" },
  { "sku": 104, "productName": "PVC Fitting" }
]

Filtering and specific properties​

vl-response-transformation:

$[inStock = true and category = "Hardware"].{"sku": id, "productName": name}

Result:

[
  { "sku": 101, "productName": "Steel Bracket" }
]

Grouping​

vl-response-transformation:

(
  $products := $;
  $products{category: {"name": name, "price": price}}
)

Result:

{
  "Hardware": [
    { "name": "Steel Bracket", "price": 12.5 },
    { "name": "Wood Screw", "price": 0.15 }
  ],
  "Plumbing": [
    { "name": "Copper Pipe", "price": 8.75 },
    { "name": "PVC Fitting", "price": 3.2 }
  ]
}

Sorting records​

vl-response-transformation:

$^(price).{"sku": id, "productName": name, "price": price}

Result (ascending by price):

[
  { "sku": 103, "productName": "Wood Screw", "price": 0.15 },
  { "sku": 104, "productName": "PVC Fitting", "price": 3.2 },
  { "sku": 102, "productName": "Copper Pipe", "price": 8.75 },
  { "sku": 101, "productName": "Steel Bracket", "price": 12.5 }
]

Sum of all prices​

vl-response-transformation:

{ "totalValue": $sum(price) }

Result:

{ "totalValue": 24.6 }

Renaming and ignoring properties​

vl-response-transformation:

$.{
  "sku": id,
  "productName": name,
  "productCategory": category,
  "unitPrice": price,
  "available": inStock
}

Result (drops internalRef and createdAt):

[
  { "sku": 101, "productName": "Steel Bracket", "productCategory": "Hardware", "unitPrice": 12.5, "available": true },
  { "sku": 102, "productName": "Copper Pipe", "productCategory": "Plumbing", "unitPrice": 8.75, "available": true },
  { "sku": 103, "productName": "Wood Screw", "productCategory": "Hardware", "unitPrice": 0.15, "available": false },
  { "sku": 104, "productName": "PVC Fitting", "productCategory": "Plumbing", "unitPrice": 3.2, "available": true }
]

Error handling​

If the vl-response-transformation header contains an invalid JSONata expression, it is ignored and the raw, untransformed response is returned instead.

Limitations​

  • The total request, including headers and URL, cannot exceed 10 KB.
  • The response size, before or after transformation, cannot exceed 6 MB.

Further reading​

Last updated on