Enstore API Documentation
Introduction
The Enstore API lets you write a feature-complete custom Enstore client. Every resource used in Enstore is accessible through the API. Some examples of what you can do with the API are:
- Integrate an existing retail management or accounting application with Enstore, similar to how Checkout integrates with Enstore.
- Build your own custom web store front-end, ranging from a website to a full-blown desktop application.
- Create your own application to manage Enstore, similar to the Enstore Admin web-app.
- Create short scripts to programmatically control Enstore features.
Intended Audience
This document is intended for anyone who wants to understand how to use the Enstore API. Its purpose is to make you familiar with the architecture of the Enstore API. After reading you'll be able to build your own custom solution that can fetch, update and delete resources.
Requirements
The things you need before you can get started:
- Knowledge of a programming language that lets you parse JSON and issue HTTP requests.
- Basic knowledge of the GET, PUT, POST and DELETE requests in HTTP, as well as HTTP's and REST's concept of a resource.
- An Enstore API account. To get one, sign up for a new store and join the early access program at the top of this page.
Transport Protocol
The Enstore API uses the HTTP protocol for default transport and the HTTPS protocol for secure transport.
Endpoint URIs
URI Syntax
The Enstore API works with uniquely identifiable resources. Every resource is identified by it's universal resource locator (url). The following url is the default base url to identify which store and API version you are using. Resources in the API can be identified in two ways; 1) a single specific resource and 2) a collection of resources.
| url | description |
|---|---|
| /[store-handle]/api/[api-version]/[resource-name].[resource-format] | A resource collection. |
| /[store-handle]/api/[api-version]/[resource-name]/[resource-uuid].[resource-format] | A single resource. |
There is a difference between a url with and without a trailing slash. The Enstore API does not support urls with a trailing slash.
Parameters
Most resources take optional GET parameters. These can used to for example filter or sort a resource. Specific parameters are described in the resource documentation.
Methods
HTTP GET is used to retrieve resources, DELETE is used to delete resources and PUT is used for requests that add a new or modify an existing resource.
| HTTP method | Description | Body |
|---|---|---|
| GET | Retrieve one or more resources | |
| PUT | Create or modify a single resource | A resource in the requested format |
| POST | Same as PUT | Same as PUT |
| DELETE | Delete one or more resources |
A resource does not have to implement every HTTP method supported. For example: The settings resource cannot be deleted. Requesting a resource using an unsupported method will result in a 400 error. Consult resource specific documentation to learn which HTTP methods are supported by that resource.
Getting the response
Response types
All successful requests, except PUT requests, will result in a '200 OK' response. A PUT request will result in a '201 Created' response. The type of unsuccessful responses depends on the type of error.
An error made by the user will return 400 Bad Response, 401 Unauthorized or 404 Not Found. The response body will always contain a detailed description of the error. The response body matches the format supplied with the FORMAT parameter. A user error response could look like:
HTTP/1.1 400 Bad Request { errorCode1: errorMessage, errorCode2: errorMessage }
Note: These errors are meant for debugging purposes. It is advised to not display these errors to your end-users directly.
The Enstore API returns a 500 Internal Server Error response when a request cannot be handled. In most cases this means that the URI is malformed. The body for an Internal Server Error response contains a general error string.