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

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

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

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

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

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

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

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
  }
*/