HCMS REST

{'The HCMS REST interface consists of two types of objects': 'Schemas define properties of entities and their mapping to the censhare data model. Entities are data instances linked to a Schema.'}

Introduction

This document assumes that the Headless CMS endpoint is running on http://localhost:8080/, if your endpoint is located somewhere else you need to adjust the URLs in the examples. Furthermore, we assume that the permission checking is disabled.

Creating a Schema

The basic schema definition structure follows the JSON schema structure. The JSON below defines a simple user entity type with the properties name, email and id:

{
    "cs:asset.type": "person.user.",
    "title": "user",
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "email": {"type": "string"},
        "id": {
            "type": "integer",
            "cs:feature.key": "censhare:asset.id"
        }
    }
}

Properties that are related to censhare specific semantics are prefixed with cs:. cs:asset.type is a mandatory property that specifies which censhare asset type is used to map the entities to, in this case person.user.. The second noteworthy property is cs:feature.keywhich specifies that the property id is mapped to the censhare feature censhare:asset.id, which happens to be censhare's internal primary key. Properties without explicit mapping specification such as nameand email are mapped to censhare features that are automatically created.

Assuming you have saved the JSON above to user-schema.json the schema is registered with a PUT call to the REST interface:

curl -X PUT http://localhost:8080/hcms/v1.0/schema/user -d @user-schema.json --header "Content-Type: application/json"

Note that the name of the schema is defined by the path segment after the schema endpoint it is put to (/hcms/v1.0/schema/<schema-name>). The same call can be used to update the schema.

List registered Schemas

You can obtain a list of registered entities with a GET request to the schema endpoint, e.g.

curl http://localhost:8080/hcms/v1.0/schema

As a result you get a JSON object listing the registered schemas including their names and URLs:

{
    "user": {
        "name": "user",
        "link": "http://localhost:8080/hcms/v1.0/schema/user"
    }
}

Create Entities

To work with the entities of a given schema you can access them through the entity endpoint path (/hcms/v1.0/entity/<schema-name>). Entities are created by posting a JSON that conforms to the schema:

{
  "name":"Karl",
  "email" : "karl@censhare.com"
}

If you have saved the data above to the file user-karl.json you can create the user in the system by posting it to the entity endpoint of the schema:

curl -X POST http://localhost:8080/hcms/v1.0/entity/user/ -d @user-karl.json --header "Content-Type: application/json"

As a response you receive the JSON of the created entity containing a populated property id. This is because id is mapped to the primary key which is autogenerated by the censhare server:

{
    "name": "Karl",
    "id": 13691,
    "email": "karl@censhare.com"
}

Read Entities

You can read entities with a GET request to their entity path followed by the primary key: /hcms/v1.0/entity/<schema-name>/<primary-key>. In the case of the user above the call looks like this:

curl http://localhost:8080/hcms/v1.0/entity/user/13691

Access existing assets

In order for standard censhare assets to be available through the Headless CMS endpoint the assets need to be tagged with the output channel assigned to the Headless CMS instance in its OSGi service configuration. Assets created through the endpoint is tagged with the assigned output channel automatically.

Update Entities

Updating entities works with the same URL as reading but with a put call sending the new JSON data: /hcms/v1.0/entity/<schema-name>/<primary-key>. To update the email address of user Karl we need to post an updated JSON like this to the endpoint:

{
  "name":"Karl",
  "email" : "karl@censhare.co.uk"
}

Assuming the JSON is saved in the file user-karl-new.json an update can be performed with curl:

curl -X PUT http://localhost:8080/hcms/v1.0/entity/user/13691 -d @user-karl-new.json --header "Content-Type: application/json"

The full JSON data must be sent for an update. Properties which are not present or null results in the deletion of the respective feature of the asset.

Note that it is not possible to update the id property since it represents the censhare internal primary key and is therefore, like a few other manual mappings, immutable. Any value present for the update is ignored.

Query Entities

The entity path for a given schema (/hcms/v1.0/entity/<schema-name>) can be used to list all entities of the given schema. For example:

curl -X GET http://localhost:8080/hcms/v1.0/entity/user

This returns something similar to the following JSON depending on the data in your system:

{
    "result": [
        {
            "email": "karl@censhare.uk.co",
            "name": "Karl",
            "id": 13691
        },
        {
            "name": "Jack",
            "id": 13700,
            "email": "jack@censhare.com"
        },
        {
            "name": "Jill",
            "id": 13701,
            "email": "jill@censhare.com"
        }
    ],
    "count": 3,
    "limit": 100,
    "offset": 0,
    "total-count": 3,
    "page": {
        "last": "http://localhost:8080/hcms/v1.0/entity/user?offset=0",
        "first": "http://localhost:8080/hcms/v1.0/entity/user?offset=0",
        "current": "http://localhost:8080/hcms/v1.0/entity/user?offset=0"
    }
}

As you can see the result is provided in paged form including information about the current page, related page and the total result set.

Paging

The paging can be influenced with the query parameters limit, which specifies the number of results per page, and offset specifying the result from which the page starts. The following example returns just the second user Jack.

curl http://localhost:8080/hcms/v1.0/entity/user?limit=1&offset=1

Sorting

A sorting of the result can be specified by the query parameter order naming the property to order by. Adding the character - in front of the property indicates a descending order, secondary sort keys can be appended by using , as a separator. Please note that sorting by certain manually mapped properties is not possible. Here is an example for ordering by name with a secondary descending ordering by email:

curl http://localhost:8080/hcms/v1.0/entity/user?order=name,-email

Resulting in something like this:

{
    "result": [
        {
            "name": "Jack",
            "id": 13700,
            "email": "jack@censhare.com"
        },
        {
            "name": "Jill",
            "id": 13701,
            "email": "jill@censhare.com"
        },
        {
            "name": "Karl",
            "id": 13691,
            "email": "karl@censhare.uk.co"
        },
        {
            "name": "Karl",
            "id": 13702,
            "email": "karl@censhare.com"
        }
    ],
    "offset": 0,
    "limit": 100,
    "count": 4,
    "total-count": 4,
    "page": {
        "current": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&order=name%2C-email",
        "last": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&order=name%2C-email",
        "first": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&order=name%2C-email"
    }
}

Conditions

Query conditions can be stated with the parameter query. These consist of properties (e.g. name or id), operators (e.g. = and !=) and values as JavaScript literals (e.g. "Karl" or 13691). For instance name="Karl" with escaping:

curl http://localhost:8080/hcms/v1.0/entity/user?query=name%3D%22Karl%22

This returns a similar result to the JSON below:

{
    "result": [
        {
            "name": "Karl",
            "id": 13691,
            "email": "karl@censhare.uk.co"
        },
        {
            "name": "Karl",
            "id": 13702,
            "email": "karl@censhare.com"
        }
    ],
    "offset": 0,
    "limit": 100,
    "count": 2,
    "total-count": 2,
    "page": {
        "current": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&query=name%3D%22Karl%22",
        "last": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&query=name%3D%22Karl%22",
        "first": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&query=name%3D%22Karl%22"
    }
}

You can also combine the operator with logical operators (e.g. and &, or |, not !) and use brackets to specify precedence: name="Karl"&id!=13691, as curl command:

curl http://localhost:8080/hcms/v1.0/entity/user?query=name%3D%22Karl%22%26id!%3D13691

This returns:

{
    "result": [{
        "name": "Karl",
        "id": 13702,
        "email": "karl@censhare.com"
    }],
    "offset": 0,
    "limit": 100,
    "count": 1,
    "total-count": 1,
    "page": {
        "current": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&query=name%3D%22Karl%22%26id%21%3D13691",
        "last": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&query=name%3D%22Karl%22%26id%21%3D13691",
        "first": "http://localhost:8080/hcms/v1.0/entity/user?offset=0&query=name%3D%22Karl%22%26id%21%3D13691"
    }
}

Hint: the curl utility can provide urlencoding for you - just use combination of -G and --data-urlencode

curl http://localhost:8080/hwcms/v1.0/entity/user -G --data-urlencode 'query=name="Karl"&id!=13691'

Delete Entities

Entities are deleted by a DELETE request at the entities path. As result, the asset the entity is mapped to is physically removed and can not be restored. Using curl such a request looks like this:

curl -X DELETE http://localhost:8080/hcms/v1.0/entity/user/13691

Delete a Schema

You can delete a schema by sending a DELETE request to the schemas URL. Note that data related to the schema is not deleted, but it can become inaccessible through the Headless CMS until a matching schema is created again.

curl -X DELETE http://localhost:8080/hcms/v1.0/schema/user