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

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

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.