public final class BrightpearlApiClient extends Object
Main client class for the Brightpearl API. This supports public and private apps of both types, system and staff. An instance of this class is designed to be shared amongst many apps and accounts if necessary.
An instance is thread-safe assuming the instance of ClientFactory provided is
thread-safe, as all implementations provided with this library are. Instances are not specific to any account and can
be safely reused for multiple accounts.
| Modifier and Type | Class and Description |
|---|---|
class |
BrightpearlApiClient.ApiSession
An authenticated API session configured with a Brightpearl customer account and headers needed to authenticate calls
for a single app of any type.
|
| Modifier and Type | Method and Description |
|---|---|
BrightpearlApiClient.ApiSession |
createSession(AppAuthorisation authorisation)
Creates a session an app and account.
|
MultiResponse |
execute(AppAuthorisation authorisation,
MultiRequest multiRequest)
Executes a multi message request.
|
MultiResponse |
execute(AppAuthorisation authorisation,
MultiRequestBuilder multiRequestBuilder)
Convenience method equivalent to
execute(AppAuthorisation, MultiRequest), this calls MultiRequestBuilder.build()
on the supplied builder for executing the request. |
<T> T |
execute(AppAuthorisation authorisation,
ServiceWriteRequest<T> serviceRequest)
Make a POST, PUT or DELETE call to the API.
|
<T> T |
execute(AppAuthorisation authorisation,
ServiceWriteRequestBuilder<T> serviceRequestBuilder)
Convenience shortcut for
execute(AppAuthorisation, ServiceWriteRequest). |
String |
fetchLegacyAuthToken(Account account,
UserCredentials userCredentials)
Using Brightpearl account details and user credentials, attempts authentication of the user and returns an auth
token if the request was successful.
|
String |
fetchStaffToken(PrivateAppIdentity appIdentity,
UserCredentials userCredentials)
Using private app details and user credentials, attempts authentication of the user and returns their staff token
if they are authorised to use the app.
|
String |
fetchStaffToken(PublicAppIdentity appIdentity,
Account account,
UserCredentials userCredentials)
Using private app details and user credentials, attempts authentication of the user and returns their staff token
if they are authorised to use the app.
|
<T> T |
get(AppAuthorisation authorisation,
ServiceReadRequest<T> serviceRequest)
Make a GET or OPTIONS call to the API, and extract the expected response entity from the JSON returned.
|
<T> T |
get(AppAuthorisation authorisation,
ServiceReadRequestBuilder<T> serviceRequestBuilder)
Convenience shortcut for
get(AppAuthorisation, ServiceReadRequest). |
Response |
getHttpResponse(AppAuthorisation authorisation,
AbstractServiceRequest serviceRequest)
Executes a request and returns the response as an unparsed string of JSON together with the HTTP status
code and headers, exactly as returned by the
Client implementation. |
<T> SearchResults<T> |
search(AppAuthorisation authorisation,
SearchRequestBuilder<T> serviceRequestBuilder)
Convenience shortcut for
search(AppAuthorisation, ServiceSearchRequest). |
<T> SearchResults<T> |
search(AppAuthorisation authorisation,
ServiceSearchRequest<T> serviceRequest)
Makes a GET call to a search API, and deserialises the response into a
SearchResults object that contains
meta information, reference data and a list of results. |
public String fetchLegacyAuthToken(Account account, UserCredentials userCredentials)
BrightpearlServiceException will
be thrown, with an error code that, in most cases, starts with "GWY".account - Details of customer account to authenticate with.userCredentials - Credentials of an API-enabled user in the account.public String fetchStaffToken(PrivateAppIdentity appIdentity, UserCredentials userCredentials)
BrightpearlServiceException
will be thrown, with an error code that, in most cases, starts with "GWY".appIdentity - Details of a private app, including the Brightpearl customer account.userCredentials - Credentials of user in the account.public String fetchStaffToken(PublicAppIdentity appIdentity, Account account, UserCredentials userCredentials)
BrightpearlServiceException
will be thrown, with an error code that, in most cases, starts with "GWY".appIdentity - Details of a public app.account - A Brightpearl customer's account details.userCredentials - Credentials of user in the account.public BrightpearlApiClient.ApiSession createSession(AppAuthorisation authorisation)
BrightpearlApiClient.ApiSession instance. This contains a reference to the instance.public MultiResponse execute(AppAuthorisation authorisation, MultiRequestBuilder multiRequestBuilder)
execute(AppAuthorisation, MultiRequest), this calls MultiRequestBuilder.build()
on the supplied builder for executing the request.authorisation - App and account authorisation details.multiRequestBuilder - Multimessage request builder to be executed.MultiResponse object containing the results.public MultiResponse execute(AppAuthorisation authorisation, MultiRequest multiRequest)
Executes a multi message request. Multi-messages can decrease latency when sending multiple write requests, and
count as only one request for rate limiting purposes. Use MultiRequestBuilder to assemble a multi message.
Errors executing the multi message request itself are thrown as exceptions from this method and generally indicate
that none of the individual requests have been executed by Brightpearl, though this cannot be guaranteed. For
example if the connection was broken after the request was sent, the result cannot be recovered. Errors in the
responses for individual requests are stored in the ServiceResponse corresponding to the request, so they
can be handled individually.
The Brightpearl multi message API supports sending messages containing between two and ten and individual requests. This client simplifies the use of this API by supporting any number of individual requests. If the supplied multi message wrapper contains only one request it will be sent direct to the relevant API, and if the wrapper contains more than ten requests it will be split into batches of ten and executed in serial. In both cases this method attempts to mimic the behaviour that would be expected if all the requests had been sent in one multi-message. However there are limitations to be aware of.
Single request: If the MultiRequest supplied contains only one request, it is sent direct to the
relevant API. HTTP transport errors are thrown by this method, and the response from the Brightpearl API is
returned in a mocked up MultiResponse wrapper with the wrapper status set to 200 if the individual
response had status 200, and 207 otherwise.
More than ten requests: The requests are split up into batches of between two and ten (batches of one are
avoided for consistency) and sent to the multi message API in sequence. HTTP transport exceptions will only be
thrown if the first batch fails with these errors; if a later batch fails with a transport error that batch and
all following ones will be aborted (regardless of the OnFailOption) and their request IDs included in
the unprocessedRequestIds field of the response. This is done so that the results of any successful batches can
be returned and inspected, and the list of unprocessed IDs handled, but it doesn't match the behaviour of the
Brightpearl API. If the status code of a batch is not 200, and the OnFailOption is OnFailOption.STOP,
later batches are not sent, otherwise all batches will be run barring transport errors.
A batch of between two and ten requests is guaranteed to be sent as a single multi message, and therefore will
avoid behaviour that may not exactly match that provided by Brightpearl. Clients that have complex error recovery
requirements should avoid sending less than two or more than ten requests. The MultiMessageUtils.split(MultiRequest)
utility may be used to split a request into batches.
authorisation - App and account authorisation details.multiRequest - Multimessage request to be executed.MultiResponse object containing the results.public <T> T get(AppAuthorisation authorisation, ServiceReadRequestBuilder<T> serviceRequestBuilder)
get(AppAuthorisation, ServiceReadRequest). Calls build on the
supplied builder and makes the call to the API.T - Type of expected response.authorisation - App and account authorisation details.serviceRequestBuilder - Builder for read request to be executed.public <T> T get(AppAuthorisation authorisation, ServiceReadRequest<T> serviceRequest)
BrightpearlClientException are thrown if
there is a failure, and other runtime exceptions may be thrown by custom implementations of ClientFactory.T - Type of expected response.authorisation - App and account authorisation details.serviceRequest - A read request to be made.public <T> SearchResults<T> search(AppAuthorisation authorisation, SearchRequestBuilder<T> serviceRequestBuilder)
search(AppAuthorisation, ServiceSearchRequest). Calls build on the
supplied builder and makes the call to the API.T - Type of expected response.authorisation - App and account authorisation details.serviceRequestBuilder - Builder for search request to be executed.SearchResults object containing parsed results and meta information.public <T> SearchResults<T> search(AppAuthorisation authorisation, ServiceSearchRequest<T> serviceRequest)
Makes a GET call to a search API, and deserialises the response into a SearchResults object that contains
meta information, reference data and a list of results.
If a valid cached response is available this will be returned. Transport errors and other request failures are
thrown as subclasses of BrightpearlClientException unless a custom HTTP client or rate limiter implementation
throws a different type.
This method uses the column names returned in the search metadata to populate objects of the requested type with
values from each array in the results. Therefore the expected response type declared in the search request should
be a flat object (i.e. only primitives, Strings and Dates) with fields either named or annotated with
com.google.gson.annotations.SerializedName according to the column names expected. In many cases, the
more complex type used for resource GETs will be unsuitable for use with the corresponding resource search.
T - Type of expected response.authorisation - App and account authorisation details.serviceRequest - The search request to be executed.SearchResults object containing parsed results and meta information.public <T> T execute(AppAuthorisation authorisation, ServiceWriteRequestBuilder<T> serviceRequestBuilder)
execute(AppAuthorisation, ServiceWriteRequest). Calls build on the
supplied builder and makes the call to the API.T - Type of expected response. Use Void.class if no response body is expected.authorisation - App and account authorisation details.serviceRequestBuilder - Builder for write request to be executed.Void.public <T> T execute(AppAuthorisation authorisation, ServiceWriteRequest<T> serviceRequest)
BrightpearlClientException are thrown if there
is a failure, and other runtime exceptions may be thrown by custom implementations of ClientFactory.T - Type of expected response. Use Void.class if no response body is expected.authorisation - App and account authorisation details.serviceRequest - A write request to be made.Void.public Response getHttpResponse(AppAuthorisation authorisation, AbstractServiceRequest serviceRequest)
Executes a request and returns the response as an unparsed string of JSON together with the HTTP status
code and headers, exactly as returned by the Client implementation.
This method bypasses the detection of failure response codes and error messages in the response body provided
by other methods, so does not throw specific exceptions such as BrightpearlAuthException.
Rate limiting is supported.
This method may be used to execute all types of request.
An exception will only be thrown for HTTP transport errors, which will usually result in a BrightpearlClientException
unless a custom HTTP client implementation throws a different type.
authorisation - App and account authorisation details.serviceRequest - Read request to be sent.Copyright © 2014. All Rights Reserved.