Bootic API
The Bootic API is implemented as JSON over HTTP.
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"
}
}
}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
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.
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.
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.
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.