15 Sep Hubert API Overview
Authorization
Access to the Hubert API’s is granted by the secret API key. To authorize the request, user is supposed to deliver it in the following HTTP header:
Authorization: ApiKey <API key value>
Customer can have multiple API keys with different permissions in the system if needed.
External id
When the customer data model is configured inside of Hubert system – each component of the definition receives the unique external id(in the form of string). These ids are subsequently used in each API call to operate on the Hubert entities.
Usually, those ids are created in prefixed form for easier readability and support. For example: customer Important Corp. can have their data stored under id: important:main_data
Complete list of all external ids is delivered to the customer after schema configuration.
Entities exposed via API
The following entities can be accessed via Hubert API:
- Contents – content in Hubert is the equivalent of record in classical databases. Each content contains the collection of fields. The set of fields is defined by the content’s schema.
- Links – links define the relations between contents.
- Enumeration lists – schema can define some fields to be of enumerated type (only values from predefined collection are allowed). Using the API, customer can define/modify the collection of predefined values.
- Typologies – typologies in Hubert describe the nested hierarchies of types.
This set effectively allows customers to fully operate on the data model defined in Hubert.
Language identification
To uniquely identify the language we use the following notation, composed of three parts:
- Language id according to ISO_639-2 norm.
- Country id according to ISO 3166-1 alfa-3 norm.
- Alphabet – one of three values:
- lat – latin alphabet
- cyr – cyrillic alphabet
- inv – not relevant
Alphabet is needed to handle the situations where the data in the different alphabet language is transliterated/transcripted to the (for example) latin one.
Basic API methods for data upsert
In this chapter we will show how to add/update enumerations and contents. Let’s start from the most basic call to insert the enumeration.
Enumerations
Enumerations can be upserted using the following URL with the POST method:
/enum
with the following request in the body:
{
"name": "My Enum",
"eid": "myname.myenum",
"values": {
"_array": [
{
"eid": "myname.myenum.firstitem",
"value": 0,
"displayOrder": 0,
"name": "item 1",
"resDictionary": {
"values": {
"_array": [
{
"lang": "eng-GBR-lat",
"value": "First item"
},
{
"lang": "fra-FRA-lat",
"value": "Premier article"
}
],
"_arrayProc": "fullSync"
}
},
{
"eid": "myname.myenum.seconditem",
"value": 1,
"displayOrder": 1,
"name": "item 2",
"resDictionary": {
"values": {
"_array": [
{
"lang": "eng-GBR-lat",
"value": "Second item"
},
{
"lang": "fra-FRA-lat",
"value": "Deuxième article"
}
],
"_arrayProc": "fullSync"
}
},
}
}
],
"_arrayProc": "fullSync"
},
}
This call will create (or update if already created) the definition of simple “My Enum” enumeration with two items:
- item 1 – with the name translated to English and French
- item 2 – with the name translated to English and French
The translations are provided for different GUI languages. If no translation is available – the main name (item 1, item 2) is used in UI.
What is _arrayProc ?
Every array in the API has the additional parameter called _arrayProc. Value of this parameter decides how the collection will be updated. This parameter can have one of the following three values:
- upsert – update the listed collection elements or add them if they do not exist in collection. The rest of current collection elements is not changed.
- delete – delete all the elements in the collection.
- fullSync – bring the collection to the exactly the same state as sent in request. Items present in the request will be upserted. Items not present – will be deleted.
Contents
Upsert of content is much more complex as it can upsert the whole structure of interlinked records in one request. You will find the detailed description in the full specification.
Content upsert request consists of several major parts:
- Technical information – like external id, schema external id and information if the record is marked for deletion.
- Channel connection array – allowing to specify the channels the records has to be connected to (plus information about the start and end time if applicable)
- Field array – allowing to specify the values of the fields of the content.
- Links array – allowing to specify the relations to other records of various types.
- Media record array – if the content has some Phoboss photos attached, the identifiers of those photos can be sent to create the attachments in the Hubert system.
- Rubric assignment array – allowing to specify the rubrics records has to be selected in.
- Typology – allowing to specify the classification of the record.
- Workflow state array – to automatically set the workflow states of the record.
What is important – the links array can include the full definition of the linked records and the structure of linking can be nested. This feature allows to upsert quite complex groups of records linked together using just one API call.
Content can be upserted just by using the POST method on the following endpoint:
/content
Example request (updating one main content and two links) may look like this:
{
"eid": "s_evnt_ed4c119ff7c34943b71ac6694e303d13",
"eidSchema": "s:event",
"channel": {
"eid": "s:event",
"eventEndUTC": "/Date(1546358400000)/",
"eventStartUTC": "/Date(1546358400000)/",
"regions": {
"_array": [
{
"eid": "s:event:main"
}
],
"_arrayProc": "upsert"
}
},
"fields": {
"_array": [
{
"eid": "s:event:official_name",
"values": {
"_array": [
{
"lang": "inv-INV-inv",
"val": [
"Morecambe FC vs Carlisle United"
] }
],
"_arrayProc": "upsert"
}
},
{
"eid": "s:event:heimspiel_eid",
"values": {
"_array": [
{
"lang": "inv-INV-inv",
"val": [
"8750917"
] }
],
"_arrayProc": "upsert"
}
},
{
"eid": "s:event:short_name",
"values": {
"_array": [
{
"lang": "fra-FRA-lat",
"val": [
"MOR vs CAR"
] },
{
"lang": "ita-ITA-lat",
"val": [
"MOR vs CAR"
] },
{
"lang": "eng-GBR-lat",
"val": [
"MOR vs CAR"
] },
{
"lang": "deu-DEU-lat",
"val": [
"MOR vs CAR"
] }
],
"_arrayProc": "upsert"
}
},
{
"eid": "s:event:full_name",
"values": {
"_array": [
{
"lang": "fra-FRA-lat",
"val": [
"Morecambe FC vs Carlisle United"
] },
{
"lang": "ita-ITA-lat",
"val": [
"Morecambe FC vs Carlisle United"
] },
{
"lang": "eng-GBR-lat",
"val": [
"Morecambe FC vs Carlisle United"
] },
{
"lang": "deu-DEU-lat",
"val": [
"Morecambe FC vs Carlisle United"
] }
],
"_arrayProc": "upsert"
}
}
],
"_arrayProc": "upsert"
},
"isDeleted": false,
"links": {
"_array": [
{
"eid": "s:event:stage",
"reference": {
"eid": "s_stag_7273cde779304888814ea8e0fbaaac3d",
"eidSchema": "s:stage",
"fields": {
"_array": [],
"_arrayProc": "upsert"
},
"isDeleted": false,
"links": {
"_array": [
{
"eid": "s:stage:season",
"reference": {
"eid": "s_seas_7e30b474d33f481f9221bf8422dde71b",
"eidSchema": "s:season",
"fields": {
"_array": [],
"_arrayProc": "upsert"
},
"isDeleted": false,
"links": {
"_array": [
{
"eid": "s:season:tournament",
"reference": {
"eid": "s_tour_5e3d180df4d2425781821ba3bfa5aebe",
"eidSchema": "s:tournament",
"fields": {
"_array": [],
"_arrayProc": "upsert"
},
"isDeleted": false,
"nestedOrder": null
}
}
],
"_arrayProc": "upsert"
},
"nestedOrder": null
}
}
],
"_arrayProc": "upsert"
},
"nestedOrder": null
}
},
{
"eid": "s:event:team1",
"reference": {
"eid": "s_team_9db39b11a2e140629c09af246ba09436",
"eidSchema": "s:team",
"fields": {
"_array": [
{
"eid": "s:team:official_name",
"values": {
"_array": [
{
"lang": "inv-INV-inv",
"val": [
"Morecambe Football Club"
] }
],
"_arrayProc": "upsert"
}
}
],
"_arrayProc": "upsert"
},
"isDeleted": false,
"nestedOrder": null
}
},
{
"eid": "s:event:team2",
"reference": {
"eid": "s_team_0e211964150b4243b0116c8d09aa5c20",
"eidSchema": "s:team",
"fields": {
"_array": [
{
"eid": "s:team:official_name",
"values": {
"_array": [
{
"lang": "inv-INV-inv",
"val": [
"Carlisle United 1903 Football Club"
] }
],
"_arrayProc": "upsert"
}
}
],
"_arrayProc": "upsert"
},
"isDeleted": false,
"nestedOrder": null
}
}
],
"_arrayProc": "upsert"
},
"nestedOrder": null
}
and the system responds with the collection of assigned ids:
{
"eid": "s_evnt_ed4c119ff7c34943b71ac6694e303d13",
"id": "41146290-829d-4eff-8524-1c9db363e08b",
"iid": 211287354,
"mod": 0
}
NOTE: The return structure contains the mod value. This value indicates if the request caused any changes in Hubert database. Before applying the changes, Hubert API checks if there is any change – if not, the change is simply skipped. If skipped, the mod value contains 0. If otherwise – 1.
This mechanism allows us to change the internal timestamps of data only in case when something is really changed.
Basic API methods for data retrieval
The same objects are used to upsert and to retrieve Hubert entities. Retrieval methods use the external id to find the proper entity. For instance:
GET /enum/eid/{enum eid}
returns the array of structures describing the enumeration definition. {eid} can be a single external id, list of external ids separated by comma or * when the list of all available enumerations have to be returned.
The same rule applies to the following methods:
GET /channel/eid/{channel eid}
GET /content/eid/{schema eid}/{content eid}
GET /typology/eid/{typology eid}
Where the first returns the array of channel definitions, second – array of contents and the third – array of typology definitions.Search for:
Sorry, the comment form is closed at this time.