Media type

Bootic API response bodies comply with the JSON-HAL media-type, and add custom extensions (documented where needed) to specify the following generic representations:

Base entity

All entities have optional _links and _embedded fields.

{
  "_links": {
    "self": {
      "href": "https://api.bootic.net/v1/shops/3/products/iphone-5.json"
    }
  },
  "title": "iPhone 5",
  "price": 20000,
  "_embedded": {
    "shop": {
      "name": "Acme",
      "url": "www.acme.com"
    }
  }
}

Schema

Normal attributes are keys at the root of an object. Special attributes are prefixed with a “_” as per the HAL specification.

_links
Optional. A set of items that describe navigational links, distinct from entity relationships. A link’s key (or rel attribute) describes the relationship and an href attribute points to the target URI. Entities should include a link rel to self if there’s a dedicated URI for them. In the HAL JSON media-type, this is represented as
{
  "_links": {
    "self": {
      "href": "https://api.bootic.net/v1/shops/3/products/iphone-5.json"
    }
  }
}
_embedded
Optional A set of sub-entities associated with the parent entity. The value of each entity can be another entity object, or an array of entities. Each entity must conform with the same entity spec as the top-level entity, with attributes and optional _links and sub _embedded properties.
{
  "_embedded": {
    "shop": {
      "_links": {
        "self": {
          "self": "https://api.bootic.net/v1/shops/2.json"
        }
      },
      "name": "Acme Corp.",
      "subdomain": "acme"
    },
    "variants": [
      {
        "sku": "AABB",
        "name": "default"
      },
      {
        "sku": "BBAA",
        "name": "Leather case"
      }
    ]
  }
}

See the product resource for an example.

Results

A results entity represents a paginated list of entities. It must conform with _links and _embedded attributes like all entities, but it also must have an items attribute assigned to an array of entities within the _embedded block. It may or may not have more entities with additional sub entities in the _embedded object.

If paginated, the properties must include total_items, page and per_page.

{
  "total_items": 100,
  "page": 1,
  "per_page": 20,
  "_links": {

  },
  "_embedded": {
    "items": [

    ]
  }
}

Schema

total_items
Required. The total number of items for the current query. If paginated, items could be a sub set of all items.
page
Required. Current page number
per_page
Required. How many items are configured to return for each page of results.
_embedded
items
Required An array of entities in the result set. Entities in this array must conform with the full base entity spec.
{
  "items": [
    {
      "_links": {
        "href": "..."
      },
      "title": "iPhone 4"
    },
    {
      "_links": {
        "href": "..."
      },
      "title": "iPhone 5"
    }
  ]
}

See the products results resource for an example.

The optional _links attribute is part of the HAL spec and its function is to guide both developers and programs by inter-linking resources just like you would expect in regular HTML pages.

Each link is composed of a relation and an href pointing to the resources location on the network.

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

In the example above, “self” is the name of the link relation. It tells you that this is a link back to the current resource.

As per the Web Linking specification, this API uses registered relation names such as “self”, “next”, “last” or “previous” for things like pagination and navigating from one resource to the next.

Bootic also defines and documents its own relation names. Whenever you encounter a relation name in an API response, you can refer to its corresponding documentation on this site to learn more about what to expect from the corresponding resource. Bootic-defined relation names are prefixed by “btc:”. Example “btc:all_products”, “btc:orders”, “btc:all_shops”.

The HAL Browser app allows you to explore the API by following these links around and exploring your account's data and allowed operations.

Some links are “templated”, meaning that they include special syntax to denote optional parameters such as search queries and filters.

Clients can leverage templated links by following the URI Template specification. Templated links will include the templated boolean flag.

{
  "_links": {
    "btc:all_products": {
      "href": "https://api.bootic.net/v1/...{?page,per_page,1,collections,tags,shop_subdomains}",
      "templated": true
    }
  }
}

You can read the HAL documentation for more on links.

Non-GET links will also include method property denoting the expected HTTP method to use.

{
  "href": "https://api.bootic.net/v1/products/{id}",
  "templated": true,
  "method": "put"
}

Link relation names might show different data depending on the context they appear. For example, the “self” link always refers more data about the direct entity it is part of.