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
HTTP
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",
        [...]
    }
}
Core SDK
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",
            [...]
        }
    }
  */
});
Node SDK
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",
            [...]
        }
    }
  */
});
Python SDK
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
HTTP
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
Core SDK
builton.orders.get(
    '<order-id>',
    { urlParams: { expand: 'user, items.product' } }
).then(console.log);
Node SDK
builton.orders.get(
    '<order-id>',
    { urlParams: { expand: 'user, items.product' } }
).then(console.log);
Python SDK
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.
Nuts & Bolts - Previous
Retrieve Items
Next - Nuts & Bolts
Pagination
Last updated 1 year ago