Entity Types

APIs for creating and manipulating entity types

Entity Types are a main component of the BitBroker system. You will find more details about entity types, within the key concepts section of this documentation.

Creating a New Entity Type

New entity types can be created by issuing an HTTP/POST to the /entity/:eid end-point.

In order to create an entity type, you must select a unique entity type ID (eid) for it.

curl http://bbk-coordinator:8001/v1/entity/country \
     --request POST \
     --include \
     --header "Content-Type: application/json" \
     --header "x-bbk-auth-token: your-token-goes-here" \
     --data-binary @- << EOF
     { \
         "name": "Countries",  \
         "description": "All the countries in the world as defined by the UN", \
         "schema": {}, \
         "timeseries": { \
             "population": { \
                 "period": "P1Y", \
                 "value": "people", \
                 "unit": "x1000" \
             } \
         } \
     }
EOF

This will result in a response as follows:

HTTP/1.1 201 Created
Location: http://bbk-coordinator:8001/v1/entity/country

The following validation rules will be applied to the body of a new entity type request.

Attribute Necessity Validation Rules
eid
required
String between 3 and 32 characters long
Consisting of lowercase letters, numbers and dashes only
Starting with a lowercase letter
Conforming to the regex expression ^[a-z][a-z0-9-]+$
name
required
String between 1 and 64 characters long
description
required
String between 1 and 2048 characters long
schema
optional
A valid JSON Schema document
timeseries
optional
A list of timeseries which are present on this entity type
timeseries.id
required
String between 3 and 32 characters long
Consisting of lowercase letters, numbers and dashes only
Starting with a lowercase letter
Conforming to the regex expression ^[a-z][a-z0-9-]+$
timeseries.period
required
A string conforming to the ISO8601 duration format
timeseries.value
required
String between 1 and 256 characters long
timeseries.unit
required
String between 1 and 256 characters long

Details about the meaning of these attributes can be found within the key concepts section of this documentation. The schema attribute is a powerful concept, which is explained in more detail there.

Updating an Entity Type

Existing entity types can have their profile updated by issuing an HTTP/PUT to the /entity/:eid end-point.

In order to update an entity type, you must know its entity type ID (eid).

curl http://bbk-coordinator:8001/v1/entity/country \
     --request PUT \
     --include \
     --header "Content-Type: application/json" \
     --header "x-bbk-auth-token: your-token-goes-here" \
     --data-binary @- << EOF
     { \
         "name": "Countries",  \
         "description": "This is a new description for countries", \
         "schema": {}, \
         "timeseries": { \
             "population": { \
                 "period": "P1Y", \
                 "value": "people", \
                 "unit": "x1000" \
             } \
         } \
     }
EOF

This will result in a response as follows:

HTTP/1.1 204 No Content

The validation rules for updated entity type information, are the same as that for creating new entity types.

List of Existing Entity Types

You can obtain a list of all the existing entity types by issuing an HTTP/GET to the /entity end-point.

curl http://bbk-coordinator:8001/v1/entity \
     --header "x-bbk-auth-token: your-token-goes-here"

This will return a JSON array as follows:

[
    {
        "id": "country",
        "url": "http://bbk-coordinator:8001/v1/entity/country",
        "name": "Countries",
        "description": "This is a new description for countries"
    }
    // ... other entity types here
]

Each entity type on the system will be returned within this array. Note: There is currently no paging on this API.

Details of an Existing Entity Type

You can obtain the details of an existing entity type by issuing an HTTP/GET to the /entity/:eid end-point.

In order to obtain details of an entity type, you must know its entity type ID (eid).

curl http://bbk-coordinator:8001/v1/entity/country \
     --header "x-bbk-auth-token: your-token-goes-here"

This will return a JSON object as follows:

{
    "id": "country",
    "url": "http://bbk-coordinator:8001/v1/entity/country",
    "name": "Countries",
    "description": "This is a new description for countries",
    "schema": {},
    "timeseries": {
        "population": {
            "unit": "x1000",
            "value": "people",
            "period": "P1Y"
        }
    }
}

Deleting an Entity Type

Existing entity types can be deleted from the system by issuing an HTTP/DELETE to the /entity/:eid end-point.

In order to delete an entity type, you must know its entity type ID (eid).

curl http://bbk-coordinator:8001/v1/entity/country \
     --request DELETE \
     --include \
     --header "x-bbk-auth-token: your-token-goes-here"

This will result in a response as follows:

HTTP/1.1 204 No Content