Box API

The Box API can create, get, update, delete, and list boxes which store inventory items.

Note that inventory “boxes” store item entries, each of which represents a real “container”. Containers are typically bags, but may be boxes (not inventory boxes though) in some cases.

All routes except item retrieval require authentication, which is handled by auth. Idempotent routes use the GET method while non-idempotent routes use POST.

Base Box API endpoint:

  • /api/box/ when the response contains zero or one models.Box

  • /api/boxes/ when the response contains two or more models.Box es

api_box_routes.api_box_get_static(box_id)

Get a single inventory box by box ID. Route forms a permalink (static) URL.

GET /api/box/get/<box_id>
Returns:

200 on success with models.Box,

400 if box ID was malformed,

404 if box was not found

api_box_routes.api_box_get_dynamic()

Get a single inventory box by box ID. Route URL is mutable by box ID (dynamic).

GET /api/box/get?box_id=<box_id>
POST /api/box/get [<box_id>]
Returns:

200 on success with the desired models.Box,

400 if box ID was not found,

400 if box ID was malformed,

404 if box was not found,

500 if box ID was not the expected length

api_box_routes.api_box_create()

Create an inventory box with provided name attribute.

POST /api/box/create [<name>, <api_key>]

Box ID will be generated programmatically and returned in the success model.

models.Box contains a variety of attributes, however the only user-mutable attribute is the box name.

Requires authentication scope auth.Scope.BOX_CREATE

Returns:

200 on success with the created models.Box,

400 if a box with the desired name already exists,

400 if API key was malformed,

401 if API key was invalid,

403 if user does not have required scope,

404 if user was not found,

404 if name was malformed,

500 if any other error while authenticating

api_box_routes.api_box_update()

Update one or more attributes on a single inventory box, identified by box ID.

POST /api/box/update [<name>, <box_id>, <api_key>]

models.Box contains a variety of attributes, however the only user-mutable attribute is the box name. All other attributes cannot be updated.

Requires authentication scope auth.Scope.BOX_UPDATE

Returns:

200 on success with the updated models.Box,

400 if no attributes to update were provided,

400 if box ID was malformed,

400 if API key was malformed,

401 if API key was invalid,

403 if user does not have required scope,

404 if box was not found before updating,

404 if box was not found after updating,

500 if any other error while authenticating

api_box_routes.api_box_delete()

Delete a single inventory box, identified by box ID.

POST /api/box/delete [<box_id>, <api_key>]

Requires authentication scope auth.Scope.BOX_DELETE

Returns:

200 on success with the deleted models.Box,

400 if box ID was malformed,

400 if API key was malformed,

401 if API key was invalid,

403 if user does not have required scope,

404 if box was not found,

500 if more than one box was found,

500 if any other error while authenticating

api_box_routes.api_boxes_list()

List one or more inventory boxes with optional ordering.

GET /api/boxes/list?sortby={*<box_attributes>}&direction={ASC,DESC}&limit=<limit>&offset=<offset>
POST /api/boxes/list [sortby={*<box_attributes>}, <direction={ASC,DESC}>, <limit>, <offset>]

Available (all optional) parameters:

  • sortby: the name of any attribute in models.Box (as a string). Results will then be sorted based based on this column. No sorting by default.

  • direction: either ASC to sort the results in ascending order or DESC to sort the results in descending order. ASC by default.

  • limit: the (maximum) number of returned boxes. common.RET_ENTITIES_DEF_LIMIT default, up to a maximum of common.RET_ENTITIES_MAX_LIMIT.

  • offset: the index offset within the database to respond with. 0 by default.

Returns:

200 on success with a list of models.Box es,

400 if any sorting attributes were malformed,

400 if sortby is present and is not a valid sort key,

400 if direction is not ASC or DESC,

400 if limit is not an integer (digit string),

400 if offset is not an integer (digit string)

api_box_routes.api_boxes_count()

Count the total number of inventory boxes.

GET /api/boxes/count

This endpoint does not follow a standard models.Model list format. Instead, the count is embedded within the standard response body as

{ 'count': box_count (int) }
Returns:

200 on success with the total box count (see formatting above),

500 if the box count returned a non-one number of values