What is an API?
An Application Programming Interface (API) is a set of messages that allow two separate computer systems to exchange data. The Brightpearl API will allow external systems to access selected data stored in your account without using the web interface.
An API facilitates a ‘conversation’ between two systems, and you will often hear the terms ‘request’ and ‘response’. System A makes a request for information from System B; System B then sends a response with the requested information. A request-response pair is called a ‘message’.
The most common use of an API is to extract data from a system, but an API can also be used to ‘invoke functionality’. This means System A asks System B to do something on its behalf, like send an invoice or move some stock between warehouses.
The term API predates the Internet, and used to refer to two parts of a single computer program communicating with each other. When you make an API available over the Internet, the API is commonly referred to as a set of ‘web services’.
When Brightpearl integrates with third-party systems, like Shopify or MailChimp, we use their API. When you do something in the application via the web interface (such as adds a tag to a contact for email marketing), our system tells MailChimp that something needs to be done.
In this scenario, Brightpearl is a ‘client’ of the MailChimp API . We have to write software to communicate with their API .
If you, as a Brightpearl customer, want to work with information in your Brightpearl account, you need to use the Brightpearl API . If you want, you can build a system to talk to both APIs, a bit like an interpreter. Let's call this a connector:
Building a connector
This is where both parties in the integration (say Brightpearl and Amazon) present their API to a third-party developer to build a connector.
The connector software is hosted on some other server (i.e. neither Brightpearl's servers or Amazon's) and periodically contacts (or ‘polls’) both APIs to see if any new work needs to be done. This can be quite inefficient as you either have to poll frequently, causing work for both systems, or accept that some actions are not taken immediately.
Brightpearl API concepts
The Brightpearl application makes use of a set of private web services (or just ‘services’), each of which performs a particular set of tasks. For example, the ‘warehouse’ service is responsible for stock control and product availability and the ‘order’ service is responsible for creating and managing sales orders. Breaking an application into a set of services is a common programming technique, and is called ‘Service Oriented Architecture’ or SOA.
The goal of the Brightpearl API is to give you direct access to exactly the same set of services that the Brightpearl application uses, but over the Internet and with additional security checks.
Entities in Brightpearl such as a Contact, Order, Product or ShippingMethod are called ‘resources’. Our API is designed so that other systems will achieve their goals by interacting with resources. Resources can be created, updated, viewed and deleted.
Almost everything can be done using these messages, so for example changing the address of a warehouse is achieved by updating a Warehouse resource.
This technique is not unique to Brightpearl; it is actually following a standard for creating web service APIs called REST (Representational State Transfer, but everyone just says REST). There is a little bit of terminology that is worth knowing about REST:
To view some data is to GET a resource.
To create a brand new entity is to POST a resource.
To modify an existing entity is to PUT a resource.
To remove an existing entity is to DELETE a resource.
What could I do with the API?
The idea of providing a public set of web services is that you can do anything that your imagination (and the messages) will support. We're driving the project with the intention of supporting the following kinds of integration first:
- Integrate a 3rd party eCommerce store like Shopify; create products in Brightpearl to see them appear on your eCommerce store, and as orders are placed on your store, they automatically appear in Brightpearl.
- Connect to a fulfilment / warehouse management service; as you create Goods-out notes in the application they can get picked up by a warehouse system for shipment.
- Synchronize your Brightpearl contact database with another CRM system.
- Query contacts, add notes etc via an iPhone app.