Structure of JSON responses

Whenever you send a request to the Brightpearl API, you will receive an HTTP response. Depending on the type of request you made, the HTTP response message body may be empty (typically for DELETE messages), but if the body is not empty, it will always be JSON object with the following structure:

{
    "response":  //some JSON structure
    "errors": [] //an array of error objects
}

Null values

The Brightpearl API does return variable names if the value is unset/null. This means that response and errors variables are mutally exclusive; if you see one in a response, the other will not be present.

Response

The value of response varies between messages and can be any  valid JSON structure . For example, the following are all valid responses:

{
    "response": 0
}

{
    "response": "Brightpearl"
}

{
    "response": [0, "Brightpearl"]
}

{
    "response": {
        "id": 0,
        "name": "Brightpearl"
    }
}

Use HTTP status codes

In a RESTful API, it is considered bad practice to interrogate the body of a message just to see if the request was executed successfully and can lead to problems parsing the response if it was not. Instead, you should use the  HTTP status code  of the response to check the overall outcome of your request before attempting to parse the response.

Errors

An array of errors is stored in the errors variable if your request could not be processed as expected, a full description of the  Brightpearl API error mechanism is here , but some example error responses are below:

{
  "errors": [
    {
      "code": "CMNC-404",
      "message": "Cannot find the resource /app/somebrokenuri"
    }
  ]
}

{
  "errors": [
    {
      "code":"CMNC-010",
      "message": "You must supply a JSON formatted body with your request"
    }
  ]
}

{ 
  "errors": [
    {
      "code":"WHSB-038",
      "message": "The name Main Warehouse is already in use by warehouse with ID 3"
    },
    {
      "code": "WHSC-070",
      "message": "You provide an address ID for each warehouse. 
                    Address IDs must be greater than zero."
    }
  ]
}

Content-Type

When receiving a response from the Brightpearl API, you should check the Content-Type response header before attempting to parse the response. A response from Brightpearl will alway have a Content-Type of

application/json;charset=UTF-8

If the response is anything other than this, it is likely that you were unable to connect to Brightpearl's servers, and have instead received content from a firewall, your ISP or a wireless network login process.