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.

GET https://api.builton.dev/payment_methods/<payment_method_id>?expand=user HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
"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.

GET /orders/<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.