Expanding Objects
Is that a nested object in your pocket, or are you just happy to see me?
It is possible to expand the nested objects within a main object. For example, an Order might have an associated User ID. If you want to expand the actual user information, you can use the
expand query parameter.HTTP
Core SDK
Node SDK
Python SDK
GET https://api.builton.dev/orders/<order_id>?expand=user HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt -or- service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
---------------
HTTP/1.1 200 OK
Content-Type: application/json
{
[...],
"items": [...],
"payments": [...],
"total_amount": 1337.42,
"user": {
"first_name": "John",
"last_name": "Doe",
[...]
}
}
const BuiltOn = require('@builton/core-sdk');
const builton = new BuiltOn({
bearerToken: '<jwt>',
apiKey: '<builton-api-key>',
});
builton.orders.get(
'<order-id>',
{ urlParams: { expand: 'user' } }
).then((order) => {
console.log(order);
/*
Order {
[...],
"items": [...],
"payments": [...],
"total_amount": 1337.42,
"user": {
"first_name": "John",
"last_name": "Doe",
[...]
}
}
*/
});
const BuiltOn = require('@builton/node-sdk');
const builton = new BuiltOn({
bearerToken: '<jwt -or- service-account-key>',
apiKey: '<builton-api-key>',
});
builton.orders.get(
'<order-id>',
{ urlParams: { expand: 'user' } }
).then((order) => {
console.log(order);
/*
Order {
[...],
"items": [...],
"payments": [...],
"total_amount": 1337.42,
"user": {
"first_name": "John",
"last_name": "Doe",
[...]
}
}
*/
});
from builton_sdk import Builton
builton = Builton(api_key=<builton-api-key>, bearer_token=<jwt -or- service-account-key>)
order = builton.order().get('<order-id>', expand='user')
print(order.user)
""
{
"first_name": "John",
"last_name": "Doe",
[...]
}
""
You can also nest
expand requests with the dot property. For example, requesting payments.payment_method on an order will expand the payments property into a list of Payment objects, and will then expand the payment_method property for each Payment object into a full Payment Method object.You can expand multiple objects at once. Just separate items in the query with commas.
HTTP
Core SDK
Node SDK
Python SDK
GET /orders/<order-id>?expand=user,items.product HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt -or- service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
builton.orders.get(
'<order-id>',
{ urlParams: { expand: 'user, items.product' } }
).then(console.log);
builton.orders.get(
'<order-id>',
{ urlParams: { expand: 'user, items.product' } }
).then(console.log);
builton.order().get('<order-id>', expand='user, items.product')
This will expand the user, the items and the product in each item.
By using the expanded parameters, you are getting more information. This increases the payload, which may increase the API response time some.
Last modified 2yr ago