We feel that it is easier for a developer to work with an API if they understand (and hopefully agree with) the guiding principles behind the API design
An API for developers
We aim to provide an API that is easy to use and that is well documented, but to get the most out of the API, you should have a background in software development or have access to a developer. There are two reasons for this:
- We use exactly the same API internally as we offer externally, so the API you are using is the same as the one our developers use. This means that we deliver new API features regularly, but those features are designed to meet the needs of our own developers as well as API users.
- The Brightpearl API is designed to be efficient and complete - in practise this means we need to use some advanced techniques and less obvious structures that API beginners may not have had much experience with.
If you don't have a development background or access to a developer, please get in touch and we'll let you know about freelance developers who have experience in working with the Brightpearl API.
The Brightpearl API follows the REST (REpresentational State Transfer) design pattern, rather than other API designs you might see (such as SOAP and XML-RPC).
RESTful Web Services
Our API design is heavily influenced by the book RESTful Web Services by Leonard Richardson and Sam Ruby. If you are planning to work with the Brightpearl API, we thoroughly recommend that you buy and refer to this book.
Resources not methods
REST APIs talk in terms of 'resources' not 'methods'. In the Brightpearl API a resource is one of the various entities that Brightpearl helps you manage and manipulate such as Contacts, Orders and Products. Behaviour is managed by creating (POST), modifying (PUT or PATCH), reading (GET) and deleting (DELETE) resources.
This contrasts with SOAP or XML-RPC style APIs which often express functionality in terms of 'methods' such as shipOrder or importProduct.
Both styles of API have their benefits - we can't deny that a method-oriented API would mean fewer messages, especially for integrators, but a resource-oriented API offers much, much greater flexibility.
Play to the strengths of HTTP
Most non-RESTful APIs completely ignore the error handling and content-type management built into HTTP. In practice this means that the content of every response will need to be parsed and analysed to understand what the result of a request was. The Brightpearl API makes full use of the facilities offered by HTTP, especially HTTP status codes. We thoroughly recommend that you bookmark and refer to the HTTP 1.1 specification.
Why not use XML?
XML is a perfectly good way of transporting data, but we think it is not appropriate for the Brightpearl API for the following reasons:
- XML is verbose - closing tags and namespacing add a lot weight to every message.
- XML is computationally expensive and complex to parse. XML parsing is still not a trivial task, as evidenced by the wide variety of techniques and parsers still available for what should be a solved problem by now.
- XML is brittle - it is very hard to create XML based APIs and API clients that can handle changes to an API
- XML Schemas are often overkill and are rarely implemented completely - XML's best feature (in our opinion) is schema support. But schemas take a very long time to implement and really only benefit you at implementation time. Once your application is written and stable, schemas are generally redundant.
So what's so good about JSON?
Generally speaking, the negative points about XML are all addressed by JSON. It is terse, lightweight and flexible. It has support for most programming languages.
Its main weakness is that it's a pain to document, as it does not have schemas or annotations to act as hooks for documentation generators.
Performance, consistency, readability
This is our list of priorities when building a new API message. Ideally every message should be readable, failing that it should at least be consistent - identical fields in two messages should have identical names.
However there are some messages that we deem to be high-performance messages. In this case we will sacrifice both readability and consistency to maintain a high level of performance. The best example of this is Product Availability GET which is designed to be fast enough to be used in real time on an ecommerce integration and uses techniques not seen anywhere else in the API.