Item API

The Item API can create, get, update, delete, and list inventory item(s).

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 Item API endpoint:

  • /api/item/ when the response contains zero or one models.Item

  • /api/items/ when the response contains two or more models.Item s

api_item_routes.api_item_get_static(item_id)

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

GET /api/item/get/<item_id>
Returns:

200 on success with models.Item,

400 if item ID was malformed,

404 if item was not found

api_item_routes.api_item_get_dynamic()

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

GET /api/item/get?item_id=<item_id>
Returns:

200 on success with the desired models.Item,

400 if item ID was not found,

400 if item ID was malformed,

404 if item was not found,

500 if item ID was not the expected length

api_item_routes.api_item_create()

Create an inventory item with provided attributes.

POST /api/item/create [*<item_attributes>, <api_key>]

All item attributes are required as listed:

  • box_id: identifier.Identifier

  • mfg_part_number: str

  • quantity: int

  • description: str

  • digikey_part_number: str

  • mouser_part_number: str

  • jlcpcb_part_number: str

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

Requires authentication scope auth.Scope.ITEM_CREATE

Returns:

200 on success with the created models.Item,

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 any item parameter was malformed,

500 if any other error while authenticating

api_item_routes.api_item_update()

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

POST /api/item/update [*<item_attributes>, <item_id>, <api_key>]

Available attributes to update/modify are:

  • box_id: identifier.Identifier

  • mfg_part_number: str

  • quantity: int

  • description: str

  • digikey_part_number: str

  • mouser_part_number: str

  • jlcpcb_part_number: str

At least one attribute must be updated, though updating more than one is supported. Item IDs and creation user/time cannot be updated. Items must be deleted and re-created to change these attributes.

Requires authentication scope auth.Scope.ITEM_UPDATE

Returns:

200 on success with the updated models.Item,

400 if no attributes to update were provided,

400 if item 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 item was not found before updating,

404 if item was not found after updating,

500 if any other error while authenticating

api_item_routes.api_item_delete()

Delete a single inventory item, identified by item ID.

POST /api/item/delete [<item_id>, <api_key>]

Requires authentication scope auth.Scope.ITEM_DELETE

Returns:

200 on success with the deleted models.Item,

400 if item 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 item was not found,

500 if more than one item was found,

500 if any other error while authenticating

api_item_routes.api_items_list()

List one or more inventory items with optional ordering.

GET /api/items/list?sortby={*<item_attributes>}&direction={ASC,DESC}&limit=<limit>&offset=<offset>

Available (all optional) parameters:

  • sortby: the name of any attribute in models.Item (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 items. 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.Item s,

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_item_routes.api_items_count()

Count the total number of inventory items.

GET /api/items/count

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

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

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

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