REST API User Guide

• Introduction
• API Authentication
• API Request Limit
• JSON Request Examples
• API Client Examples

Introduction

The Bluepark API (Application Programming Interface) provides a means of communication between Bluepark sites and other software. For example, you might want to integrate your Bluepark site with order management software, accounting software, order fulfilment companies or EPOS systems. The API allows such software to be integrated directly, or via specifically written software which sits between the Bluepark API and the foreign API.

Bluepark's API adheres to a REST or RESTful architectural style. This means that the API uses the HTTP protocol for communication, specifically the GET, POST, PUT and DELETE request methods. The API accepts query string parameters for GET and DELETE requests, and JSON data for POST and PUT requests, always responding with standard JSON data.

This is typically known as a CRUD API:

• Create = POST
• Retrieve = GET
• Update = PUT
• Delete = DELETE

A number of resources, including assets such as orders and products, can be manipulated via these methods using a secure HTTPS connection. Please visit the page below to view and test all available resources and methods.

API Specification

API Authentication

API authentication is handled using HTTP Basic authentication. All API requests must be made using a secure HTTPS connection. Credentials and permissions for API access are created via the site's Admin Manager.

From the Admin Panel Menu:

• Navigate to the Admin menu and select Admin Users
• Click on the green Plus button or select an existing admin user to enter the Admin Editor
• Arriving on the Properties tab, check the box to Enable API Access
• Save your changes. You can now view all of your API access credentials
• Optionally, use the Permissions tab to customise the access level

When you establish a connection to the API access URL, you must use your API username and API key to authenticate the request. Any failed authentication attempts will result in a 401: Unauthorized response code being returned.

API Request Limit

The API is a very powerful tool which enables many potentially database-intensive requests to be made of Bluepark's servers within a short period of time. Due to the potential consequences of misuse, we have imposed a request limit which is reflected in the X-Requests-Limit and X-Requests-Remaining response headers returned after every request.

The current API request limits are 1,000 requests per hour for the Enterprise Park package, 500 requests per hour for the Business Park package and 250 requests per hour for the Retail Park package.

JSON Request Examples

Below are some formatted JSON request examples which illustrate how simple POST and PUT API requests can be created in order to achieve various outcomes.

Create an Order Using Minimal Information:

It is possible to create a new order by submitting only an e-mail address and a product (including just a SKU and quantity). If the e-mail address relates to an existing user, all of their billing information will be completed automatically. Similarly, if the product SKU relates to an existing product, all of the product information will be retrieved.

If the order total is not included in the request, it will be calculated automatically by the system, along with VAT and discounts, in the same way as for a new order being placed via the site.

Resource: orders

[
    {
        "email_address": "john@bluepark.co.uk",
        "products": [
            {
                "sku": "asics-gel-blu-8",
                "quantity": 1
            }
        ]
    }
]

Process an Order as Completed in Full:

To fully complete an order, mark all products as shipped, inform the customer via e-mail, take any outstanding payment and adjust stock, simply send a status with an ID of 2 for completed, and include the "do_process" parameter.

Resource: orders

[
    {
        "id": 1,
        "status": {
            "id": 2
        },
        "do_process": true,
        "do_send_email": true,
        "do_take_payment": true
    }
]

Process an Order as Pending and Partially Shipped:

To keep an order pending, mark one or more products as shipped, inform the customer via e-mail, take any outstanding payment and adjust stock, simply send a status with an ID of 1 for pending, include the "do_process" parameter, and include the "products" collection detailing the products to be shipped.

Resource: orders

[
    {
        "id": 1,
        "status": {
            "id": 1
        },
        "products": [
            {
                "id": 1,
                "quantity_shipped": 1
            }
        ],
        "do_process": true,
        "do_send_email": true,
        "do_take_payment": true
    }
]

Update (Change) the Quantity in Stock of a Product or Variant:

The easiest way to update the quantity in stock of a product or variant is to use the associated SKU. The "skus" resource preserves variant inheritance and always ensures that the correct product or variant is updated with the new quantity.

Resource: skus

[
    {
        "sku": "asics-gel-blu-8",
        "quantity_in_stock": 5
    }
]

Update (Reduce) the Quantity in Stock of a Product or Variant:

If want to reduce the quantity in stock of a product or variant, regardless of the current stock level, simply use the "do_sub_quantity" parameter. There is also a "do_add_quantity" parameter which does the opposite. Please note that processing an order will adjust physical stock automatically if your site is configured to manage inventory.

Resource: skus

[
    {
        "sku": "asics-gel-blu-8",
        "do_sub_quantity": 5
    }
]

API Client Examples

We are happy to provide our own PHP-based API client example for you to download and adapt in any way you would like. Please feel free to use this as a starting point for building your own application or integration.

API Client (PHP)