MenuClose

API Introduction and Authentication

Our API is used by Couriers, Inventory platforms, CRMs etc. 

Courier Integrations

Couriers would usually fetch "recent orders" (aka baskets), with a an extra parameter to identify only those orders that are "ready to ship", to reduce effort. Fetch orders in bulk with minimal details, or request full order line data. Fetch orders individually for full detail.

After an order label is printed, send an update back to our basket/order endpoint, with courier tracking details, and to record a delivered status in our database. You can also optionally trigger a notification to be sent to the customer (if your courier platform does not send it's own notification. We recommend this is configurable per merchant.)

Inventory Management / ERP

Post recently changed products to our product API.

Only include the minimal data to be updated. eg you could just supply code, price and stock count.

Setup a web hook in our CMS platform, to receive notifications of new orders or new customers.

Or poll hourly for new orders, or new customers. 

Post member/customer records optionally. The expectation is that the customer facing website usually has the most up to date customer information. 

Sync all objects by your own code/reference, or using our ID/reference. 

CRM

Setup web hooks for customer events, or poll hourly for new customers or updated customer records.

Customisation / New Endpoints

Website world is a very large platform, with many features. This API has exposed the most common end points required by our customers. If you require addition of a new parameter to reduce I/O, or a whole new endpoint to access whatever data, then please contact us support@website.world 

Rate Limiting

Access to our API endpoints are rate limited. You should make a maximum of 100 API requests per minute.  
It is best to impliment a queue for API updates that will detect the HTTP return code and try again in case our servers are temporarily unavailable. 

General Knowledge

Whenever possible, we have attempted to maintain some standard approaches across each endpoint. 

  • "id" = the unique ID of the object / row / data. When retrieving data, you may find a different worded ID field with the same number. These ID's are interchangeable, with "id" used for consistency. If an ID is supplied, then it will update on POST, and only return data on GET. If an ID is not provided, then it will INSERT on POST, or get an ARRAY of data on GET.
  • "mbr_id" = when data is associated with a customer, user or member, then we need to state the unique member ID for which the data is associated. This may also be referred to as "about_mbrid" or "mbr_uid" or "staff_id" etc. For consistency, we prefer to use "mbr_id" across all end points, even thought the other id name remains available for use. In many cases, if the mbr_id is not yet known, you can supply a mbr_email and mbr_name, and a mbr_id will automatically be associated based on a unique email lookup, or if not found, it will create a new member record with that email address, and update the data with the correct mbr_id. This is great for flat data systems like Zapier.

Authentication

We provide a very simple authentication method, that is suitable for connecting couriers, inventory systems, accounting systems, and connecting with other cloud services. We do not suggest you use this API for deploying phone apps or any software installed on customers devices. Having access to the API keys, potentially gives a user READ and WRITE access to all your website data via this method. 

New users are welcome to sample our api. Sending Email and Files endpoint is a privilege only for live customers. Rest all endpoints are available for sample.

Enabling the API / Obtaining Access Keys

To obtain API access keys, please...

  1. login to the CMS / Control Panel
  2. Click the Shop Setup button, or edit your target shopping page. 
  3. Click the API tab, or API's button.
  4. Scroll down and add the JSON api option.
  5. Click Enable API.
  6. An API ID and a API Key will be provided to you. The API ID identifies this instance of the integration, which identifies your website, and the default page for data creation (if page is not identified in the JSON data post)
  7. The API key can be changed to anything you wish.

End Points

This is our secure API URL:  https://api.cms-tool.net/webapps/api/... 

You can append any of our end points on the end, eg https://api.cms-tool.net/webapps/api/products

Some api end points may permit path info upon the end of the URL, eg for the requested ID, file path, etc. But please check invididual end points for allowable options.

Using the Access Keys 

You can provide the "apiID" and "apiKey" as either request headers or request parameters.

They can be GET or POST parameters. They can be POST parameters within a multipart form post also. 

We are also looking to provide an oAuth authentication method soon.

Posting JSON data

You can post your JSON payload inside a "data" request parameter...

Or you can set your header ContentType="text/json", with the content body being your JSON data

Alternatively, you may use a multipart form post content type, if you are uploading files with your API request.

For clarity, our assumption is that the posted data is in json format (or raw text/file). We do not currently accept other formats.

Retrieving Data

You can use GET or POST to retrieve data, but GET makes more sense.

You can use Accept Header to retrieve data in JSON or XML.
Examples: Use Accept:application/xml to get response data in XML. Or use "text/csv" to receive CSV results. The default format for the response will be json otherwise. All processing on the back end works with JSON, and we convert to your desired format at the last minute. 

The JSON data is always returned inside a JSON API status wrapper, indicating if your API reqest was "success":true, or "success":false, or "error":"error message here".

The actual data you desire, will be in the json element:   "data":{}  

Or if you requested a list of objects, where no ID was given, then you would get an array object  "data":{[.... ]}  

Some end points include plural named options. In general, if you POST, or GET using an ID, you will get a single JSON data object back, otherwise, it will be an array. Sometimes there is a helper element to tell you the "dataType"