Retrieve Items

Where is that thing?

You can usually retrieve items from all our Building Blocks in two ways. Either with a straight GET call or using the more advanced GET request, search. Check the respective Building Block for detailed examples.

You can use filtering, pagination and sorting to navigate through the ginormous lists you'll get if you, for example, GET /products and you have a million products.

Filter by date

Parameter	Type	Description
from_date	number	Start date, in timestamp format. Default is none.
to_date	number	End date, in timestamp format. Default is none.
date_filter	string	Date field used to filter results. Default is CREATED.

Pagination

Parameter	Type	Description
size	number	Number of items to retrieve. Default is 10.
page	number	Which page to retrieve. Default is 0.

Sorting

Parameter	Type	Description
sort	string	Field used for sorting results.

List Items

This is a straight GET call to our APIs. Here's an example that lists all your Orders, but it works the same for all the Building Blocks.

Note: You may not need the Authorization header to retrieve certain items. For example, you'd want to be able to show your products to people without requiring them to have a valid JWT. I.e., you don't have to sign in to search Amazon's website. Your user's payment methods, on the other hand, would require it.

HTTP

GET /orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

Core SDK & Node SDK

builton.orders.get({ size: 10, page: 0 }).then((page) => {
  console.log(page.current);
});

Python SDK

orders = builton.order().get_all()
print(orders)

For information about the pagination, see Pagination.

Search for Items

This method allows you to retrieve a list of items, like user_name or account_number, that match a search query without specifying that you are searching for user_name or account_number. Check the respective Building Block for detailed examples, but here's an example of searching for a particular order.

HTTP

GET /orders/search?query=<search-query> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

Core SDK & Node SDK

builton.orders.search('<search-query>', { size: 10, page: 0 }).then((page) => {
  console.log(page.current);
});

Python SDK

orders = builton.order().search(query='<search-query>', size=10, page=0)
print(orders)

For information about the pagination, see Pagination.

Search by Tag

The Building Blocks Users, Products and Resources can all have tags added to them.

There are three ways to search by tag. You can search for:

1. Any item that has that tag, even if they have other tags, too. E.g. all items that have glove as a tag . Code: ?tags=tag_1

2. Items that have multiple tags. E.g. all items that have glove and black as a tag. Code: ?tags=tag_1+tag_2

3. Items that have only one tag. E.g. a really boring glove that has no other tags. Code: ?tags=tag_1+

You can combine these into complex searches.

e.g.: ?tags=glove+red,skis+,socks

The above would return all products that have both red and glove tags, all products that only are tagged with ski, and all the socks.