HCMS First Steps

Shows the basic use of the HCMS rest interface after software installation.

The Headless CMS REST interface consists of two fundamental types of objects: Schemas that define properties of entities and how they are mapped to the internal censhare data structures and entities which are actual data instances linked to a Schema.

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, it is assumed that the permission checking is disabled and masterdata creation is enabled. Note that these are not the default settings created by commandline tool; before continue with this tutorial, they have to be changed:

BASH

./hcms -s frmis://<server-host>:30546/corpus.RMIServerSSL  -u <username> authorization create <id> --disable-security 
./hcms -s frmis://<server-host>:30546/corpus.RMIServerSSL  -u <username> configuration update <id> --no-new-masterdata true

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:

JSON

{
    "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:

BASH

curl -X PUT http://localhost:8080/hcms/v2.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/v2.0/schema/<schema-name>). The same call can be used to update the schema.

Listing registered Schemas

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

BASH

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

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

JSON

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

Creating Entities

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

JSON

{
  "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:

BASH

curl -X POST http://localhost:8080/hcms/v2.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:

JSON

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

Reading Entities

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

BASH

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

Accessing 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.

Updating Entities

Updating entities works with the same URL as reading but with a put call sending the new JSON data: /hcms/v2.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:

JSON

{
  "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:

BASH

curl -X PUT http://localhost:8080/hcms/v2.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.

Querying Entities

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

BASH

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

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

JSON

{
    "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/v2.0/entity/user?offset=0",
        "first": "http://localhost:8080/hcms/v2.0/entity/user?offset=0",
        "current": "http://localhost:8080/hcms/v2.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.

Property	Description
result	Contains the array with the entities of the current page
count	The number of entities on the current page
limit	The maximum number of entries per result page
total-count	The total number of entities returned by this query
page.last	The URL of the last result page
page.first	The URL of the first result page
page.current	The URL of the current result page
page.next	The URL of the next result page, only present if there is a successor page
page.prev	The URL of the next previous page, only present if there is a predecessor page

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.

BASH

curl http://localhost:8080/hcms/v2.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:

BASH

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

Resulting in something like this:

JSON

{
    "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/v2.0/entity/user?offset=0&order=name%2C-email",
        "last": "http://localhost:8080/hcms/v2.0/entity/user?offset=0&order=name%2C-email",
        "first": "http://localhost:8080/hcms/v2.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:

BASH

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

This returns a similar result to the JSON below:

JSON

{
    "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/v2.0/entity/user?offset=0&query=name%3D%22Karl%22",
        "last": "http://localhost:8080/hcms/v2.0/entity/user?offset=0&query=name%3D%22Karl%22",
        "first": "http://localhost:8080/hcms/v2.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:

BASH

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

This returns:

JSON

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

BASH

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

Deleting 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:

BASH

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

Deleting 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.

BASH

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