Resources

We break a Resource into two concepts; a resource as a reusable asset and a retail resource that is meant to be sold.

If not specified, an asset resource is created.

Changes since API version2019-02-01

2019-09-18 - `image` type changed to Object

image changed to Image Object.

2019-09-02 - `image_url` Deprecated

We are deprecating the old image_urland replacing it with Image Object.

Asset Resource Object

Attribute

Type

Description

method

string

The resource type. asset or retail.

user

object

User associated with the resource.

name

string

Name of the resource item.

description

string

Description of the resource item.

image

object

Imageobject for this resource.

product

object

Product associated with the resource.

tags

array

An array of tags.

human_id

string

6 character ID.

status

string

Status of the resource. Default is CREATED, other options are listed below.

Retail Resource Object

In addition to the attributes in the asset resource, the retailresource has the following attributes.

Attribute

Type

Description

_sub_products

array

An array with sub-products associated with the resource.

base_price

number

The sum of the product.price and price in all the _sub_products.

retail_price

number

The amount that this resource is sold for.

currency

string

The currency in the main product in the resource.

vat

number

The VAT from the main product in the resource. A decimal value between 0 and 1, e.g. 0.25 = 25%.

Resource Status

Default status for the resource is CREATED. Change the status by updating the resource.

Status

CREATED

PROCESSING

UTILIZED

IDLE

ON_THE_WAY_FROM

ON_THE_WAY_TO

DONE

User Role

Create a new Resource*

Parameters
HTTP
Core SDK / Node SDK
Parameters

Body Parameters

Type

Description

name

string

Name of the resource item.

product

string

Product ID to be associated with the resource.

description

string

Description of the resource item.

status

string

Status of the resource, default is CREATED other options are PROCESSING, UTILIZED, IDLE.

image

string

Image ID for this resource.

reference_id

string

Customizable ID for the resource

HTTP
Request --
POST /resources HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"name": "Electric Scooter W3E7IB",
"description": "Rent this electric scooter"
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "596c643ed57ba203be2cf1c9"},
"method" "asset",
"name": "Electric Scooter W3E7IB",
"description": "Rent this electric scooter",
[...]
}
Core SDK / Node SDK
builton.resources.create({
name: 'Electric Scooter W3E7IB',
description: 'Rent this electric scooter',
}).then(console.log);
/*
Resource {
id: '596c643ed57ba203be2cf1c9',
method: 'asset',
name: 'Electric Scooter W3E7IB',
description: 'Rent this electric scooter',
[...]
}
*/

Update a Resource*

Parameters
HTTP
Core SDK / Node SDK
Parameters

Path Parameter

Type

Description

resource_id

string

The resource’s ID

Body Parameters

Type

Description

name

string

Name of the resource item.

description

string

Description of the resource item.

user

string

User ID to be associated with a user.

status

string

Status of the resource. Default is CREATED; other options are PROCESSING, UTILIZED or IDLE.

product

string

Product ID to be associated with the resource.

image

string

Image object for this resource.

reference_id

string

Customizable ID for the resource.

HTTP
Request --
PUT /resources/596c643ed57ba203be2cf1c9 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"name": "Electric Scooter Q2EW6UV",
}
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "596c643ed57ba203be2cf1c9"},
"method" "asset",
"name": "Electric Scooter Q2EW6UV",
"description": "Rent this electric scooter",
[...]
}
Core SDK / Node SDK
builton.resources.update('596c643ed57ba203be2cf1c9', {
name: 'Electric Scooter Q2EW6UV',
}).then(console.log);
/*
Resource {
id: '596c643ed57ba203be2cf1c9',
method: 'asset',
name: 'Electric Scooter Q2EW6UV',
description: 'Rent this electric scooter',
[...]
}
*/

Retrieve a Resource by ID*

Parameters
HTTP
Core SDK / Node SDK
Parameters

Path Parameter

Type

Description

resource_id

string

The resource’s ID.

HTTP
Request --
GET /resources/596c643ed57ba203be2cf1c9 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "596c643ed57ba203be2cf1c9"},
"method" "asset",
"name": "Electric Scooter Q2EW6UV",
"description": "Rent this electric scooter",
"product": {"$oid": "58f9f856b70e2a56c4a0db3d"},
"image": {"$oid": "596c643ed57ba203be2cf2c9"},
[...]
}
Core SDK / Node SDK
builton.resources.get('596c643ed57ba203be2cf1c9').then(console.log);
/*
Resource {
id: '596c643ed57ba203be2cf1c9',
method: 'asset',
name: 'Electric Scooter Q2EW6UV',
description: 'Rent this electric scooter',
[...]
}
*/

List All Resources*

Parameters
HTTP
Core SDK / Node SDK
Parameters

Query Parameters

Type

Description

include_deleted

boolean

If true, the request also returns deleted resources.

size

number

Number of resources per page. Default is 10.

page

number

Defines which page to retrieve. Default is 0.

from_date

number

Start date, timestamp format. Default is None.

to_date

number

End date, timestamp format. Default is None.

sort

string

Field used to sort results. Default is -created.

status

string

Status of the resource. Default is CREATED; other options are PROCESSING, UTILIZED or IDLE

HTTP
Request --
GET /resources HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"_id": {"$oid": "596c643ed57ba203be2cf1c9"},
"method" "asset",
"name": "Electric Scooter Q2EW6UV",
"description": "Rent this electric scooter",
"product": {"$oid": "58f9f856b70e2a56c4a0db3d"},
"image": {"$oid": "596c643ed57ba203be2cf2c9"},
[...]
},
[...]
]
Core SDK / Node SDK
builton.resources.get().then(page => {
console.log(page.current); // First page
});
/*
[
Resource {
id: '596c643ed57ba203be2cf1c9',
method: 'asset',
name: 'Electric Scooter Q2EW6UV',
description: 'Rent this electric scooter',
[...]
},
[...]
]
*/

Search Resources by Keywords*

Search by _id, name, reference_id, description and image_url. Returns an array that matches the query. Filter the query by using pagination.

Parameters
HTTP
Core SDK / Node SDK
Parameters

Query Parameters

Type

Description

query

string

Partial or full string of name, reference_id, description or image_url.

include_deleted

boolean

If true, the request also returns deleted resources.

size

number

Number of resources per page. Default is 10.

page

number

Defines which page to retrieve. Default is 0.

from_date

number

Start date, timestamp format. Default is None.

to_date

number

End date, timestamp format. Default is None.

sort

string

Field used to sort results. Default is created.

HTTP
Request --
GET /resources/search?query=electric HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"_id": {"$oid": "596c643ed57ba203be2cf1c9"},
"method" "asset",
"name": "Electric Scooter Q2EW6UV",
"description": "Rent this electric scooter",
"product": {"$oid": "58f9f856b70e2a56c4a0db3d"},
"image": {"$oid": "596c643ed57ba203be2cf2c9"},
[...]
},
[...]
]
Core SDK / Node SDK
builton.resources.get().then(page => {
console.log(page.current); // First page
});
/*
[
Resource {
id: '596c643ed57ba203be2cf1c9',
method: 'asset',
name: 'Electric Scooter Q2EW6UV',
description: 'Rent this electric scooter',
[...]
},
[...]
]
*/

Admin Role

*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.

Create new Resources in Bulk

Parameters
HTTP
Parameters

Body Parameters

Type

Description

name

string

Name of the resource item.

description

string

Description of the resource item.

user

string

User ID to be associated with a User.

status

string

Status of the resource _default is CREATED other options are PROCESSING, UTILIZED, IDLE

product

string

Product ID to be associated with the resource.

image

string

Image ID for this resource.

reference_id

string

Customizable ID for the resource.

HTTP
Request --
POST /resources/bulk HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
[
{
"product": "58f9f856b70e2a56c4a0db3d",
"method": "asset",
"name": "First resource"
},
{
"product": "58f9f856b70e2a56c4a0db3d",
"method": "asset",
"name": "Second resource"
}
]
Response --
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"_id": {"$oid": "596c643ed57ba203be2cf1c9"},
"product": "58f9f856b70e2a56c4a0db3d",
"method" "asset",
"name": "First resource",
[...]
},
{
"_id": {"$oid": "57ee9c71d76d431f8511142f"},
"product": "58f9f856b70e2a56c4a0db3d",
"method" "asset",
"name": "Second resource",
[...]
}
]

Delete a Resource

Parameters
HTTP
Node SDK
Parameters

Path Parameters

Type

Description

<resource_id>

string

ID of the resource to be deleted.

HTTP
Request --
DELETE /resources/596c643ed57ba203be2cf1c9 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response --
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "596c643ed57ba203be2cf1c9"},
"method" "asset",
"name": "Electric Scooter W3E7IB",
"description": "Rent this electric scooter",
"deleted": true,
}
Node SDK
builton.resources.del('5e5e7580a66b2a00089308b5').then(console.log);
/*
Resource {
id: '596c643ed57ba203be2cf1c9',
method: 'asset',
name: 'Electric Scooter Q2EW6UV',
description: 'Rent this electric scooter',
delete: true
}
*/