Introduction

Overview

What is REST API? To make it simple, REST API defines a set of functions to which the developers can perform requests and receive responses. The interaction is performed via the HTTP protocol. An advantage of such an approach is the wide usage of HTTP. That is why REST API can be used practically for any programming language.

Output Formats

The REST API supports the response in JSON format.

Authentication

DCL RESTful API supports Basic authentication (defined in RFC 2617, HTTP Authentication: Basic and Digest Access Authentication). It has the advantage that it is an Internet standard, is supported by all major browsers and is a relatively simple protocol.

Basic authentication works as follows:

• If a request requires authentication, the server returns 401 (Unauthorized). The response includes a WWW-Authenticate header, indicating the server supports Basic authentication.
• The client sends another request, with the client credentials in the Authorization header. The credentials are formatted as the string “name:password”, base64-encoded.
• For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the header is formed as follows:
  Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

DCL RESTful API works only with SSL.

HTTP Verbs

HTTP verbs are used to manage the state of resources. In DCL REST API, there are three verbs used to manage resources: GET, POST and PUT. You can get the contents of the data using HTTP GET, create the data using POST and update the data using PUT.

HTTP Status Codes

Upon success, we return '200/OK' status code for GET verbs and '201/Created' status code for POST verbs.
In case of error, you get '4xx Client Error' status code (usually a '400/Bad Request', '401/Unauthorized' or '429/Too Many Requests' status code); you need to analyze the response body to get more detail about the error.

BASE URL and versioning

All URLs in REST API have the following base URL. Current version is v1.

https://api.dclcorp.com/api/v1/

Further, we offer a sandbox environment so developers can experiment without fulfill real orders.

https://api.dclcorp.com/api/sandbox/

Pagination

Our API uses pagination for resources that typically will have a lot of records. The pagination is applied to the five APIs:

• GET api/v1/items
• GET api/v1/items/returns
• GET api/v1/orders
• GET api/v1/rmas
• GET api/v1/po_receipts

Use the URI parameters page (default value: 1) and page_size (typical default value: 100) to specify the page and page size you need to retrieve. When no records are returned (or less then page_size), you have reached the end of the result set.

Test API

We also offer a functional simple interface to test any API (see the button Test API at the bottom right of the endpoint API help page).

If you use Chrome browser, you can also use the plugin Advanced REST client. Under Firefox, you can use the plugin RESTClient.

API Call Limit

Just a friendly reminder that we have introduced an "API call limit" feature that operates using a "leaky bucket" algorithm as a controller. This allows for infrequent bursts of calls, and allows your app to continue to make an unlimited amount of calls over time. The bucket size is 50 calls (which cannot be exceeded at any given time), with a "leak rate" of 2 calls per second that continually empties the bucket. If your app averages 2 calls per second, it will never trip a 429 error ("Too many requests: bucket overflow").

To avoid this error, please try to submit multiple orders with a single POST api/v1/batches call; when asking for status (items, orders or RMAs), you can also specify to retrieve multiple records with a single call.