ACU IDU User Manual

5.2.47 /api/v1/inventory

This API endpoint is used to inspect or modify the backend's inventory of items / devices.

Supported HTTP methods: GET, POST, PATCH, HEAD, OPTIONS

GET /api/v1/inventory/{itemId}

Gets the inventory item with the given ID.

Parameters:

Parameter	Description
itemId	The itemId of the item to get

Expected Payload: none.

Replied Payload: An InventoryItem record with the given ID

Return Codes:

Code	Description
200	OK, the requested InventoryItem document is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.

GET /api/v1/inventory/{itemId}/devices

Gets the list of InventoryDevice objects mapped to the given inventory item.

Parameters:

Parameter	Description
itemId	The itemId of the item to get

Expected Payload: none.

Replied Payload: An array of InventoryDevice records mapped to the item with the given ID

Return Codes:

Code	Description
200	OK, the requested InventoryDevice Array is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.

GET /api/v1/inventory/{itemId}/devices/{deviceId}

Gets the InventoryDevice objejct with the given ID combination.

Parameters:

Parameter	Description
itemId	The itemId of the item to get
deviceId	The deviceId of the device to get

Expected Payload: none.

Replied Payload: An InventoryDevice record with the given ID combination.

Return Codes:

Code	Description
200	OK, the requested InventoryDevice document is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.

POST /api/v1/inventory

Creates a new InventoryItem entry in the database.

Parameters: none.

Expected Payload:An InventoryItem record containing the fields of the record to create. The following rules apply:

Fields which are null or missing are set to 'null' in the record.
The field 'itemId' is ignored. The POST command creates a new record, the database assigns a unique itemId to the created record.
The 'modified' field is set to the time when the command is executed, a 'modified' time specified in the supplied data is ignored.

Replied Payload: The created InventoryItem record

Return Codes:

Code	Description
200	OK, the modified InventoryItem document is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.
500	DB is not writable. In this case an ApiError document is returned,describing details of the error.

POST /api/v1/inventory/{itemId}/devices

Creates a new InventoryDevice entry in the database and attaches this to the given item.

Parameters:

Parameter	Description
itemId	The itemId of the item to add the new device to

Expected Payload:An InventoryDevice record containing the fields of the record to create. The following rules apply:

Fields which are null or missing are set to 'null' in the record.
The field 'deviceId' is ignored. The POST command creates a new record, the database assigns a unique deviceId to the created record.
The field 'itemId' is ignored. The POST command always takes the the 'itemId' from the URL and sets this in the created record.
The 'modified' field is set to the time when the command is executed, a 'modified' time specified in the supplied data is ignored.

Replied Payload: The created InventoryItem record

Return Codes:

Code	Description
200	OK, the modified InventoryDevice document is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.
500	DB is not writable. In this case an ApiError document is returned,describing details of the error.

PATCH /api/v1/inventory/{itemId}

Modifies the inventory item with the given ID.

Parameters:

Parameter	Description
itemId	The itemId of the item to modify

Expected Payload:An InventoryItem record containing the fields to modify. The following rules apply:

Fields which are null or missing are not changed in the record.
To set a field to 'null' set it to an empty string.
The field 'itemId' is ignored. The PATCH command modifies the record specified in the URI, the 'itemId' ofthis record never changes.
The 'modified' field is set to the time when the command is executed, a 'modified' time specified in the supplied data is ignored.

Replied Payload: The InventoryItem record after modification

Return Codes:

Code	Description
200	OK, the modified InventoryItem document is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.
500	DB is not writable. In this case an ApiError document is returned,describing details of the error.

PATCH /api/v1/inventory/{itemId}/devices/{deviceId}

Modifies the InventoryDevice object with the given ID combination.

Parameters:

Parameter	Description
itemId	The itemId of the item to modify
deviceId	The deviceId of the device to modify

Expected Payload:An InventoryDevice record containing the fields to modify. The following rules apply:

Fields which are null or missing are not changed in the record.
To set a field to 'null' set it to an empty string.
The field 'deviceId' is ignored. The PATCH command modifies the record specified in the URI, the 'deviceId' of this record never changes.
The 'modified' field is set to the time when the command is executed, a 'modified' time specified in the supplied data is ignored.

Replied Payload: The InventoryDevice record after modification

Return Codes:

Code	Description
200	OK, the modified InventoryDevice document is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.
500	DB is not writable. In this case an ApiError document is returned,describing details of the error.

DELETE /api/v1/inventory/{itemId}

Deletes the inventory item with the given ID. As a side effect, all InventoryDevice and InventoryLogEntry objects referring to this inventory item are deleted as well.

Parameters:

Parameter	Description
itemId	The itemId of the item to delete

Expected Payload: none.

Replied Payload: none.

Return Codes:

Code	Description
204	OK, the addressed InventoryItem has been deleted.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.
500	DB is not writable. In this case an ApiError document is returned,describing details of the error.

DELETE /api/v1/inventory/{itemId}/devices/{deviceId}

Deletes the InventoryDevice obkect with the given ID combination.

Parameters:

Parameter	Description
itemId	The itemId of the item to delete
deviceId	The deviceId of the device to delete

Expected Payload: none.

Replied Payload: none.

Return Codes:

Code	Description
204	OK, the addressed InventoryDevice has been deleted.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryItem with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.
500	DB is not writable. In this case an ApiError document is returned,describing details of the error.

POST /api/v1/inventory/list

Gets a list of inventory items matching the filter information sent with the request.

Parameters: none

Expected Payload: An InventoryItem document containing the filter to be applied. Any fields in the document which are missing or null are intepreted as a wildcard. Specified fields must all match to include the item in the returned list. If a 'modified' timestamp is given in the filter description, it is interpreted as 'must be modified at this time or later'.

Replied Payload: An array of InventoryItem records fulfilling the filter spec. The list is sorted by modification time, oldest first. If no records match the filter, an empty list is returned.

Return Codes:

Code	Description
200	OK, the requested InventoryItem array is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	The backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.
500	DB is not writable. In this case an ApiError document is returned,describing details of the error.

GET /api/v1/inventory/log/{entryId}

Gets the inventory log entry with the given ID.

Parameters:

Parameter	Description
entryId	The entryId of the log entry to get

Expected Payload: none.

Replied Payload: An InventoryLogEntry record with the given ID

Return Codes:

Code	Description
200	OK, the requested InventoryLogEntry document is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryLogEntry with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.

POST /api/v1/inventory/log

Adds a new InventoryLogEntry to the database.

Parameters: none.

Expected Payload:An InventoryLogEntry record containing the fields of the record to create. The following rules apply:

log entries cannot be modified / rewritten. All fields must be supplied with their desired values.
The field 'entryId' is ignored. The POST command creates a new record, the database assigns a unique itemId to the created record.
The 'created' field is set to the time when the command is executed, a 'created' time specified in the supplied data is ignored.

Replied Payload: The created InventoryLogEntry record

Return Codes:

Code	Description
200	OK, the modified InventoryLogEntry document is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	No InventoryLogEntry with this ID exists or the backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.
500	DB is not writable. In this case an ApiError document is returned,describing details of the error.

POST /api/v1/inventory/log/list

Gets a list of inventory log entries matching the filter information sent with the request.

Parameters: none

Expected Payload: An InventoryLogEntry document containing the filter to be applied. Any fields in the document which are missing or null are intepreted as a wildcard. Specified fields must all match to include the entry in the returned list. If a 'modified' timestamp is given in the filter description, it is interpreted as 'must be created at this time or later'.

Replied Payload: An array of InventoryLogEntry records fulfilling the filter spec. The list is sorted by creation time, oldest first.

Return Codes:

Code	Description
200	OK, the requested InventoryLogEntry array is returned.
401	Not logged in. In this case an ApiError document is returned, describing details of the error.
404	The backend does not support the inventory database. In this case an ApiError document is returned, describing details of the error.