Bootic API (beta)

The Bootic API is currently in beta, and its endpoints, responses and format might change in the near future.

The Bootic API is implemented as JSON over HTTP.

  1. Getting started
  2. Introduction
  3. Conventions
  4. HTTP
  5. Authentication
  6. Media type
  7. Endpoints

Getting started

The Bootic API gives you programatic access to the data stored in your Bootic shop, allowing other developers (you!) to write their own apps and extend the core Bootic functionality.

Usage of the Bootic API requires that you own a Bootic shop and have a user role of administrator. All API calls require an access token. There are different ways of getting an access token depending on what you need to do, but first you need to register your application to get the basic credentials. Read our Getting Started Guide to understand how to register an application.

If you already have a Bootic shop, you can also use the API browser app to explore the API interactively.

Introduction

The Bootic API exposes important resources in the Bootic platform such as products, shops, shop templates and orders. The root URL is:

https://api.bootic.net/v1

API responses are designed following the HATEOAS principle that different resources should be inter-linked using URIs to minimise out of band information and simplify client implementation.

Clients are encouraged to follow links available in resources instead of building URLs themselves.

{
  "_links": {
    "self": {
      "href": "https://api.bootic.net/v1/products/1234.json"
    }
  }
}

Read more about links.

Conventions

Most endpoints include read functionality, some include write (create, update, delete) depending on your authorized scope and the type of resource.

There are two representations for read resources, summary and detail.

Summary representation

A summarized version of resources is normally included in lists and search results. It includes a subset of the total number of a resource’s attributes.

Summary representations include a self link relation pointing to the full, detailed representation.

For example, listing products for a shop will return a results representation including a list of summary product representations.

GET /v1/products.json?shop_ids=10

Detail representation

Most summary representations in a list will include a link to a detail representation encoded in the self link relation. The URL for a detailed product representation might look like:

GET /v1/shops/101/products/1234.json

Bootic API representations include links to other representations. Clients are expected to follow these links rather than hard-coding URLs as URLs might change in the future. Read about Bootic's Media Type to learn more.

HTTP

Where possible, the Bootic API strives to use appropriate HTTP verbs for each action.

Verb Description
HEAD Can be issued against any resource to get just the HTTP header info.
GET Used for retrieving resources.
POST Used for creating resources, or performing custom actions.
PUT Used for replacing resources or collections.
DELETE Used for deleting resources.

Conditional requests

Bootic’s API responses include caching headers as per the HTTP 1.1 specification. Clients are expected to use these headers and implement client-side caching of reponses. This not only removes unnecessary load from our servers but it also makes your apps faster!

For example, a request for products returns the Last-Modified header with the date of last modification for that resource.

HTTP/1.1 200 OK
Date: Thu, 08 May 2014 16:03:31 GMT
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding
X-OAuth-Scopes: admin,public
Last-Modified: Fri, 20 Jun 2014 22:34:14 GMT
Cache-Control: max-age=0, private, must-revalidate
  {
    ...
  }

Your client can now send subsequest requests to the same resource passing the Last-Modified’s value with the If-Modified-Since request header.

GET /v1/products.json HTTP/1.1
Host: api.bootic.net
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json
User-Agent: My Application
If-Modified-Since: Fri, 20 Jun 2014 22:34:14 GMT

If the resource hasn’t changed, the server will return a 304 Not Modified response status and no response body. Your client can then reuse a stored version of the content. This means the request-response cycle is much faster because no heavy payload has to be sent over the network.

HTTP/1.1 304 Not Modified
Date: Thu, 08 May 2014 16:03:31 GMT
Content-Type: application/json; charset=utf-8
Vary: Accept-Encoding
X-OAuth-Scopes: admin,public
ETag: "8586c620f06d8fe07b483b55951cc270"
Last-Modified: Fri, 20 Jun 2014 22:34:14 GMT
Cache-Control: max-age=0, private, must-revalidate

Many languages have HTTP libraries that handle HTTP caching transparently for you. For example Ruby’s Faraday HTTP client has this caching library available.

The Bootic API might enforce request rate limits in the future. Implementing client-side caching early will protect your app from said limits.

JSONp

All GET API requests accept a JSONp callback as a callback query-string and the .jsonp extension.

curl https://api.bootic.net/v1/products.jsonp?callback=MyCallback&access_token=XXX

MyCallback({
  {
    class: ["user"],
    properties: {
      name: "Ismael Celis",
      ...
    }
  }
})

Authentication

Authentication follows the OAuth2 spec. All API requests require an access_token as authentication.

The access token must be passed in the Authorization header along with every request.

$ curl -X GET -i -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' https://api.bootic.net/v1/products.json
GET /v1/products.json HTTP/1.1
Host: api.bootic.net
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json
User-Agent: My Application
Status: 200 OK
Content-Type: application/json; charset=utf-8
Connection: keep-alive
ETag: "0728e2965bd03e20a7f1c33add2f8775"
Last-Modified: Fri, 20 Jun 2014 22:34:14 GMT
Cache-Control: must-revalidate, private, max-age=0
Date: Wed, 31 Jul 2013 21:11:52 GMT
X-OAuth-Scopes: public
{

}

Access tokens are obtained by creating applications in Bootic’s authorization service and exchanging application and user credentials for temporary access tokens.

Access tokens are temporary, and there's not guarantee that they'll last forever. Clients are expected to refresh expired tokens by using one the methods listed below.

Supported OAuth2 flows

Authorization Code Grant for online applications and single sign-on
User signs-on and obtains an access token. Used by third-party apps acting on behalf of a logged-on user or that want to use Bootic as an identity provider. This flow will be familiar if you’ve used Facebook, Twitter or Google authentication before.
Implicit Grant for JavaScript and client-side apps.
This flow is optimized for JavaScript and other client-side apps that can’t store secret credentials securely.
Client Credentials Grant for server-side scripts.
Useful for automated scripts and other clients that do not act on behalf of a particular user.
Resource Owner Password Credentials Grant for trusted apps.
This flow is only suitable for trusted apps or scripts as it demands the user’s login and password.
JWT Bearer Authorization Grant for refreshing expired tokens.
Use this flow in server-side code to refresh expired user tokens.

Read more about authentication and how to get started.

Media type

All JSON responses are structured following the HAL media type specification. These conventions should allow client implementors in writing generic, extensible client libraries, or reuse existing client libraries.

{
  "_links": {

  },
  "title": "iPhone 5",
  "id": 10,
  "slug": "iphone-5",
  "_embedded": {

  }
}

While all responses comply with the basic HAL entity representation, they are grouped into two kinds of resources: a base entity, representing a basic generic resource, and results entity, an extension of base entity representing a list of resources for listing, search and filtering.

Read more about our media type.

Errors (TODO)

Read the full custom media type specification.

Endpoints

Bootic API exposes links to the different resources. You are encouraged to write code that follows links instead of hard-coding URLs.

You get a list of available links when you visit the APIs root at https://api.bootic.net/v1

The following resources are currently implemented:

Root
The API’s entry point, with relevant links and resources, including info on the authorized user. Start here!
Products
List and filter available products, read product details.
Orders
List and filter orders for authorized user/account, read order details.
Shops
List public shops, read shop details.