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.

In our sample calls, we use the standard server name and port format outlined for local installations and demos. If you have an alternative API host base URL, then enter it in the box below to update all the sample calls on this page :

Your API Host Base URL

All API calls in BitBroker require authorization. The sample calls below contain a placeholder string where you should insert your coordinator API authorization token. If you already have a token, enter it in the box below to update all the sample calls on this page:

Your Coordinator API Authorization Token

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.

Entity type IDs are required to be unique across an operating BitBroker instance.

Timeseries IDs are required to be unique within their housing entity type.

By convention, entity types are expressed in the singular, non-plural form. So, for example, product is preferred over products.

You should choose your entity type IDs (eid) with care, as these cannot be changed once created.

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

Great care should be taken when updating the JSON schema associated with an entity type. Consider whether this breaks an implicit contract that you may have made with existing data connectors for this entity type. It may make more sense to create a new entity type, if the amended schema definition is incompatible with the existing one.

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

Deleting an entity type will also delete all entity instances associated with that type from the Catalog.

Deleting an entity type will also delete all data connectors associated with that entity type. No further data contribution will be accepted for it.

Any policy authorization tokens which were issued where this entity type formed part of the data segment, will no longer return entity instances of this type. In some circumstances, this could render policy authorization tokens unfit for purpose.