The Brightpearl API is a RESTful API, and RESTful APIs are designed around the concept of manipulating resources. In the Brightpearl API, each resource is assigned a unique numeric identifier which is referred to as the resource's ID.
These IDs are positive integers. When you create a new resource it will generally be assigned the next available ID starting with 1. IDs are never reassigned, so if you were to delete a Warehouse with the ID 4, then ID 4 would never be used again.
Variable naming convention
In JSON messages, you will often see variable names which include Id as a suffix. You can infer some meaning from this variable name:
| id | This variable stores the ID of the current resource. |
| {name}Id | This variable stores the ID of a resource, the type of that resource is indicated by {name}. For example, warehouseId indicates that this is the ID of a Warehouse and that resource can be retrieved by calling Warehouse GET and supplying that ID in the URI. |
| {context}{Name}Id | This variable stores the ID of a resource, the type of that resource is indicated by {name} as above, but some disambiguation is required, so the variable is prefixed with some sort of context (i.e. sourceWarehouseId, targetWarehouseId) |
ID Sets
For the majority of interactions with the Brightpearl API, the most time consuming part of processing a message is the transmission time between your device and the Brightpearl servers. In order to minimise this overhead, many messages allow you to operate on multiple resources within a single message
For read-only (i.e GET) messages, you can generally substitute an ID Set for a ID in a URI. An ID Set can represent:
- A single ID
- A range of IDs
- An ordered list of IDs
- An unordered list of IDs
- A mixture of the above
Single ID
A single ID of a resource, e.g:
- 8
- 1000
Range of IDs
A range of IDs is two numbers separated by a - (dash, hyphen) character. The first number of the range must be lower than the second (i.e. only ascending ranges are supported)
- 8-9
- 1000-1248
Ordered list of IDs
Two or more IDs separated by a , (comma) character. An ordered list must be in ascending order with no repetition, but may contain gaps.
- 8,9
- 1000,1200,1247,1248
Unordered list of IDs
Two or more IDs separated by a . (dot, fullstop, period) character. An unordered list may not include any repeated IDs
- 8.9
- 1200.1247.1199.1248
Why use the dot character?
The more logical separator for unordered list elements is the ; (semi-colon) character, which, although legal according to the HTTP specification, causes problems with a number of web and application servers as it is often used to indicate the presence of a session ID in a URI.
Mixed lists
It is possible, but only occasionally useful, to mix ranges and lists. There are a number of restrictions: a list may be ordered or unordered but not both (no mixing commas and dots) and if the list is ordered, ranges within the list must be positioned logically and not overlap with other ranges or IDs in the list.
- 1-3,4,5
- 1000.45-58.2098.10-12
Missing IDs
When you specify an ID Set in a URI, you are implicitly saying 'I want to manipulate all those resources which exist and whose IDs are included in the ID Set'. If one of the IDs in the set does not exist, the message will generally not fail, but will instead operate on those IDs that do exist.
Destructive messages
Destructive messages (PUT, POST, DELETE) that support ID Sets, will generally behave in the same way as if you called the message separately for each resource. If an error is encountered for a single resource, the server will try to operate on the remaining resources. In this situation, you can generally expect the message to return with an HTTP 207 status code
Restrictions
Individual messages may place restrictions on the ID Sets they accept. A common restriction is to disallow ranges on expensive messages. The documentation for each message will provide the details.