IDs & ID sets

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

Destcrutive 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 restruction is to dissallow ranges on expensive messages. The documentation for each message will provide the details.

 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.