Multi-message

The multi-message is an advanced API technique intended for integrators and application developers and allows up to 10 destructive (POST, PUT, DELETE) messages to be sent to the Brightpearl API in a single HTTP request. You may mix and match any type of resource and HTTP method in a multi-message request.

The most common scenarios in which you would consider using this message are when you are:

  • Performing a data migration of many thousands of resources into Brightpearl from some other system.
  • Developing an application that will run on a high-latency internet connection (3G).
  • Building an integration that needs to send very large numbers of messages and regularly hits the request cap.

Base URI

/multi-message

Note that the multi-message is similar to the authenticate message in that it doesn't require you to specify the name of a service. So the structure of the URI is:

https://ws-{datacentre-code}.brightpearl.com/{api-version}/{account-code}/multi-message

Example message

This example shows how you could create, edit and delete three different Warehouses in a single request.

Request

{
    "processingMode": "SEQUENTIAL",
    "onFail": "STOP",
    "messages":[
        {
            "label":"LABEL1",
            "uri": "/warehouse-service/warehouse",
            "httpMethod": "POST",
            "body":{
                "name": "Bristol shipping warehouse",
                "address":{
                    "addressId": 34
                }
            }
        },
        {
            "label":"LABEL2",
            "uri": "/warehouse-service/warehouse",
            "httpMethod": "PUT",
            "body":{
                    "warehouses":[
                        {
                            "id": 10,
                            "name": "Receiving warehouse"
                        }
                    ]
            }
        },
        {
            "label":"LABEL3",
            "uri": "/warehouse-service/warehouse/45",
            "httpMethod": "DELETE"
        }
    ]
}

Response

{
    "response":{
        "processedMessages":[
            {
                "label": "LABEL1",
                "statusCode": 200,
                "body": {40}
            },
            {
                "label": "LABEL2",
                "statusCode": 200,
                "body": {}
            },
            {
                "label": "LABEL3",
                "statusCode": 200,
                "body": {}
            }
        ],
        "unprocessedMessages":[]
    }
}

As you can see, these are standard Warehouse POST, PUT and DELETE requests and responses wrapped in structures that allow us to accept and provide data that would normally be supplied as HTTP meta-data.

Effect on throttling

A multi-message, no matter how many child-messages it contains, only counts as a single request for the purposes of throttling.

Request structure

The request is an array of child-messages with instructions on the order in which the child messages should be processed and the behaviour if an error is encountered.

Processing mode

The processing mode defines the order in which the child-messages are processed with the two valid values being SEQUENTIAL and PARALLEL.

When the processingMode is set to SEQUENTIAL, the child-messages will be processed one after another in the order in which they are supplied. PARALLEL processing should be used with care, and is explained in detail at the end of this document.

On-fail behaviour

The onFail field controls how the Brightpearl API should behave if an error is encountered while processing a child-message. For the purposes of the multi-message, any non-Successful 2xx HTTP status code encountered while processing a child-message is treated as an 'error'.

When onFail is set to STOP, subsequent child-messages will not be processed and the label of each message that has not been processed will be included in theunprocessedMessages array in the multi-message response. If onFail is set to CONTINUE, the error will be ignored and processing will continue.

Messages

A minimum of two and a maximum of ten messages may be specified in the messages array.

Label

Each child-message requires a label. This is a string that allows the Brightpearl API to identify each child-message which makes it much easier for users to associate a child-message in a request with an outcome in the response. The labels can be anything you like (up to a maximum of 64 characters), but must be unique within a request (i.e. the same label can't be used for more than one child-message in a request.)

URI

This is path you would normally specify to call a message directly, without the API version and account code. For example to POST a new order, you would provide the URI /order-service/order not /2.0.0/myaccountcode/order-service/order

HTTP method

The HTTP method that you would like to perform on the resource. Valid options for httpMethod are POST, PUT and DELETE. Please note that GET and OPTIONS are deliberately excluded to prevent abuse.

Body

The JSON structure that you would normally provide as the HTTP body if you were calling a message directly. Only required if your httpMethod is PUT or POST.

Please note that the entire multi-message needs to be parseable as valid JSON. If a child-message's body cannot be parsed, the whole multi-message will not be parseable and you will receive an HTTP 400 status code.

Response structure

The response provides the HTTP status code and body of child-messages that were processed (whether they succeeded or failed) and array of labels of any messages that were not even attempted.

Overall HTTP status code

The status code of a multi-message will be 200 if, and only if, the status code of all child-messages is 200, otherwise the status code will be 207.

Processed messages

The processedMessages array contains a JSON structure describing the outcome of each message that was processed, successfully or otherwise. Messages in this array are in the same order as they were supplied in the multi-message request.

Label

The label in each response allows users to work out which child-message response relates to which child-message request.

Status Code

The HTTP status code that was returned when the child-message was processed.

Body

The data that would have been provided as the HTTP response body had the child-message been called directly.

Unprocessed messages

This is an array containing the labels of any child-messages that were not attempted because an earlier message failed and the on-fail behaviour was set to STOP.

Parallel processing

By setting the processingMode to PARALLEL, you are giving the Brightpearl API permission to run multiple processing threads and process child-messages in parallel. This can be very powerful and has the potential to cut down the overall elapsed time spent processing a set of messages.

However, you must be very careful when using this mode. You must think very carefully about the full set of child-messages you are submitting and whether it is logically sensible to run them all simultaneously. The Brighpearl API does not attempt to validate the combination of child-messages to check whether the combination is safe or makes sense.

Contraindications that suggest parallel processing is not safe:

  • When the child-messages are competing for the same resources - i.e. creating multiple Goods-Out Notes using the same products. In this situation it is likely that running messages in parallel will be slower than running them in sequence.
  • When you have not validated data yourself and are relying on the Brightpearl API to validate data. An example would be a migration of users from some other system with duplicate email addresses.
  • Where you are mixing different types of HTTP method, especially on the same type of resource. For example, a very broad DELETE child-message might be trying to delete a resource that is relied on by other child-messages
 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.