JSON-API Specifications

Hiweb API extends JSON-API standard for most of data structures and HTTP methods, for more details, please visit https://jsonapi.org

Basically speaking, Hiweb API returns a set of resources with JSON-API structure.

But due to some special demands, there're some exceptions like /api/variants PUT method, but we already documented them well in each API document section.

Document objects

All api request or response data are document objects.

Document objects are JSON objects and MUST be at the root of every request and response containing data. This object defines a document’s “top level”.

A document MUST contain at least one of the following top-level members:

  • data: the document’s “primary data”
  • errors: an array of error objects
  • meta: a meta object that contains non-standard meta-information.

The members data and errors MUST NOT coexist in the same document.

Hiweb API "documents" MAY also contain any of these top-level members:

  • links: a links object related to the primary data.
  • included: an array of resource objects that are related to the primary data and/or each other (“included resources”).

The document’s “primary data” is a representation of a single resource or an array of resources targeted by a request.

Primary data MUST be either:

  • A single resource object, a single resource identifier object, or null, for requests that target single resources.
  • An array of resource objects, an array of resource identifier objects, or an empty array [], for requests that target resource collections.

A simple example of a document for a single resource:

{
  "data": {
    "id": "...",
    "type": "...",
    "attributes": {
      "attribute1": "...",
      "attribute2": "..."
    }
  }
}

A simple example of a document for multiple resources:

{
  "data": [
    {
      "id": "...",
      "type": "...",
      "attributes": {
        "attribute1": "...",
        "attribute2": "..."
      }
    },
    {
      "id": "...",
      "type": "...",
      "attributes": {
        "attribute1": "...",
        "attribute2": "..."
      }
    },
    ...
  ]
}

Resource objects

“Resource objects” are JSON objects that appear in a Hiweb API return to represent resources.

A resource object contains the following top-level members:

  • id (string / format: UUID)
  • type (string)

Exception: The id member is not required when the resource object originates at the client and represents a new resource to be created on the server.

In addition, a resource object MAY contain any of these top-level members:

{
  "key1": "value 1", 
  "key2": "value 2"
}
  • relationships: a relationships object describing relationships between the resource and other JSON:API resources. Relationship data can be an object (one-to-one relationship) or an array of objects (one-to-many relationship). Example of a relationship object:
{
  "product": {
    "data": {
      "id": "...",
      "type": "products"
    }
  },
  "images": {
    "data": [
      {
        "id": "...",
        "type": "images"
      },
      {
        "id": "...",
        "type": "images"
      }
    ]
  }
}
  • links: a links object containing links related to the resource.
  • meta: a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship.

Below is a completed example of a JSON-API resource:

{
  "type": "variants",
  "id": "1",
  "attributes": {
    "title": "...",
    "price": 1234
  },
  "relationships": {
    "product": {
      "data": { "type": "products", "id": "..." }
    }
  },
  "links": {
    "self": "https://example.hiweb.io/api/variants/{id}"
  }
}

For more detail about all resource objects, check out the "Resource objects" section.