Schema

This document describes the information that the API returns.

All response that the API returns will be in JSON format and will have the following base shape:

{
    "self": <url>, 
    "meta": {...}, 
    "links": {...}, 
    "rel": <string>,
    "spec": <url>,
}

• self: Returns the canonical URL for such resource, most of the time the same URL you just visited.
• meta: Will contain meta information about the resource (for collections it will have pagination information).
• rel: Will indicate the type of resource accessed, either "entity", "collection" or "resource" as fallback.
• spec: Should contain a URL pointing to this website where documentation for such resource can be found.
• links: Probably the most important bit. Contain a series of keyed URLs that are related to the resource visited, this is the base for all the API navigation.

Entities

An entity represents an item on the database, this could be a brand, a model, a size, a user, etc. It refers to an individual thing.

Entities have the same base attributes described above but have these defined values:

{
    "rel": "entity",
    "meta": {
        "collection": <url>
    },
    "body": {...}
}

• rel: Will say entity, this is how you should detect that you've received an entity and should look for the body attribute to read this entity's detailed attributes.
• meta: Will contain at least one key collection that will contain the URL to the canonical collection where this entity is listed, in the case of an individual brand, you will the URL for the collection of brands. If the resource is accessible from more than one collection, you will only get one of the collections, the canonical which will remain the same.
• body: Is an object with a set of attributes for this entity, the objects may be strings, numbers, objects or arrays depending on the nature of each.

Collections

Collections refer to lists of entities, this is where you will be able to browse and navigate to a given entity.

On top of the base attributes they will have these characteristics:

{
    "rel": "collection",
    "meta": {
        "page_total": <int>, 
        "paginated": <bool>, 
        "next": <url>, 
        "current": <url>, 
        "collection_total": <int>, 
        "prev": <url>

    },
    "collection": [...]
}

• rel: Will always say collection, this is how you tell a collection.
• meta: Will contain at least these keys:
  • page_total: A number with the amount of items shown on this page.
  • paginated: Indicates whether or not this is a paginated collection.
  • next: The URL of the next page, Null if there isn't one.
  • current: The URL of the current page.
  • collection_total: The number of total items on the full collection.
  • prev: The URL of the previous page, Null if there isn't one.
• collection: A list of the items shown in the current page of the collection. Each entity should have at least an href link with the URL to the entity's detail endpoint. Each element on the collection may contain more attributes to help quickly describe each item.

---

Edit