Requests and Responses

Below is the usage of the current API implementation:

Endpoint	Method	Body	Description
`/timbr/api/get_ontologies/`	`GET`		Posts a query and returns results in JSON form
`/timbr/api/query/`	`POST`	`{ ontology_name: <ontology_name>, query: <SQL query to run> }`	Posts a query and returns results in JSON form
`/timbr/api/get_ontology/<ontology_name>`	`POST`		Gets the ontology details for a certain ontology
`/timbr/api/q/<ontology_name>/concept/<concept_name>?<filters>`	`GET`		Query a concept in a knowledge graph. A user can optionally specify `<filters>` for the properties of the concept
`/timbr/api/q/<ontology_name>/view/<view_name>?<filters>`	`GET`		Query a view in a knowledge graph. A user can optionally specify `<filters>` for the properties of the view
`/timbr/api/get_config/<config_name>`	`POST`		Gets the value of a whitelisted environment variable as specified in the `ALLOWED_CONFIG_ENVS_IN_API` environment variable
`/timbr/api/clear_cache/<ontology_name>`	`POST`		Clears the Redis cache for an ontology

Examples for calling the REST API endpoints

The following was tested using curl with MINGW64 on Windows 11

Get ontologies endpoint

Request:

curl -X 'GET' \
  'https://timbr-sample.company.com/timbr/api/get_ontologies/' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response:

Response code: 200
Response body:

{
  "data": ["timbr_supply_chain", "timbr_user_segmentation", ...],
  "status": "success"
}

Query endpoint

Request:

curl -X 'POST' \
  'https://timbr-sample.company.com/timbr/api/query/' \
  -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "select * from timbr.person limit 5",
  "ontology_name": "timbr_supply_chain"
}'

Response:

Response code: 200
Response body:

{
  "data": [{
    "entity_id": "p:2",
    "entity_type": "person",
    ...
  }, 
  ...],
  "status": "success"
}

Get ontology endpoint

Assuming the <ontology_name> is timbr_supply_chain

Request:

curl -X 'GET' \
  'https://timbr-sample.company.com/timbr/api/get_ontology/timbr_supply_chain' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response:

Response code: 200
Response body:

{
  "data": {
    "datasources": [{ ... }, ...],
    "ontology": [ { ... }, ...],
    "properties": { ... },
    "quote": "`",
    "version": "52b2f455-bd0f-f34a-a9cc-9c799b8b9e6d",
    "views": { ... },
  },
  "status": "success"
}

Query concept endpoint

Assumptions

ontology_name is `timbr_supply_chain
concept_name is `customer
filters Optional. Filters are a list of parameters for the properties or a relationship of a concept that translate into a WHERE statement in SQL. Omitting the filters will perform a SELECT * on the timbr schema of a concept.
nested Optional. false by default. If true if the data in the results should be formatted in a nested value for relationships

Nested in header

If the nested key is true then the results will be formatted only if there is a relationship or a multi-value in the filters of the GET URI endpoint

The filter paramteres can be 1..n of the following combinations:

_subj_ - The subject of the filter – A property in the knowledge graph
_op_ - The operator – The operator performed in the filter, must be one of
1. eq - Equals, in SQL: =
2. not_eq - - Not equals, in SQL != or <>
3. in - Includes, in SQL: IN(..)
4. not_in - Not includes, in SQL: NOT IN(..)
5. like - Contains, in SQL: LIKE (can be used with wildcards combinations like % and [] )
6. like - Not contains, in SQL: NOT LIKE (can be used with wildcards combinations like % and [] )
7. gt - Greater than, in SQL >
8. gte- Greater than or equal, in SQL >=
9. lt - Less than, in SQL <
10. lte - Less than or equal, in SQL <=
11. is_null - Null value, in SQL IS NULL
12. not_null - Is not null value, in SQL IS NOT NULL
_comp_ - The comparator – The comparison value(s)
_conj_ - The conjunction – For compound filters, must be either AND or OR

The order of the parameters also matter, but they can be sorted by the numbering ( _subj_, _subj1_, _subj2_ , ... )

For example: /timbr/api/q/timbr_supply_chain/concept/person?_subj_=property1&_op_=eq&_comp_=val1&_conj_=AND&_subj1_=property2&_op1_=like&_comp1_=val2&_conj1_=OR_subj2_=property3&_op2_=IN&_comp2_=val2,val3,val4&_subj3_=....

Request:

Querying the customer concept in the timbr_supply_chain knowledge graph. Applying the following filters:

customer_name property should start with the string Elizabeth POR
customer_id equals to 5503

curl -X 'GET' \
  'https://timbr-sample.company.com/timbr/api/q/timbr_supply_chain/concept/customer?_subj_=customer_name&_op_=like&_comp_=Elizabeth%20P%&_conj_=OR&_subj1_=customer_id&_op1_=eq&_comp1_=5503' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response:

Response code: 200
Response body:

{
  "data": [{
    "customer_email": "XXXXXXXXX",
    "customer_id": "5503",
    "customer_name": "Tiffany Smith",
    "customer_password": "XXXXXXXXX",
    "customer_segment": "Consumer",
    "entity_id": "5503",
    "entity_label": "Tiffany Smith",
    "entity_type": "customer"
  }, {
    "customer_email": "XXXXXXXXX",
    "customer_id": "639",
    "customer_name": "Elizabeth Pittman",
    "customer_password": "XXXXXXXXX",
    "customer_segment": "Home Office",
    "entity_id": "639",
    "entity_label": "Elizabeth Pittman",
    "entity_type": "customer"
  }, {
    "customer_email": "XXXXXXXXX",
    "customer_id": "801",
    "customer_name": "Elizabeth Parker",
    "customer_password": "XXXXXXXXX",
    "customer_segment": "Consumer",
    "entity_id": "801",
    "entity_label": "Elizabeth Parker",
    "entity_type": "customer"
  }, {
    "customer_email": "XXXXXXXXX",
    "customer_id": "10058",
    "customer_name": "Elizabeth Proctor",
    "customer_password": "XXXXXXXXX",
    "customer_segment": "Corporate",
    "entity_id": "10058",
    "entity_label": "Elizabeth Proctor",
    "entity_type": "customer"
  }],
  "executed_query": "SELECT * FROM `dtimbr`.`customer` WHERE `customer_name` LIKE 'Elizabeth P%' OR `customer_id` =  '5503'",
  "status": "success"
}

Query ontology view endpoint

Assumptions

ontology_name is `timbr_supply_chain
view_name is `customer_view
filters Optional. Filters are a list of parameters for the properties or a relationship of a view that translate into a WHERE statement in SQL. Omitting the filters will perform a SELECT * on the vtimbr schema.
nested Optional. false by default. If true if the data in the results should be formatted in a nested value for relationships

Nested in header

If the nested key is true then the results will be formatted only if there is an entity_id column in the ontology view SQL query

The filter paramteres can be 1..n of the following combinations:

_subj_ - The subject of the filter – A property in the knowledge graph
_op_ - The operator – The operator performed in the filter, must be one of
1. eq - Equals, in SQL: =
2. not_eq - - Not equals, in SQL != or <>
3. in - Includes, in SQL: IN(..)
4. not_in - Not includes, in SQL: NOT IN(..)
5. like - Contains, in SQL: LIKE (can be used with wildcards combinations like % and [] )
6. like - Not contains, in SQL: NOT LIKE (can be used with wildcards combinations like % and [] )
7. gt - Greater than, in SQL >
8. gte- Greater than or equal, in SQL >=
9. lt - Less than, in SQL <
10. lte - Less than or equal, in SQL <=
11. is_null - Null value, in SQL IS NULL
12. not_null - Is not null value, in SQL IS NOT NULL
_comp_ - The comparator – The comparison value(s)
_conj_ - The conjunction – For compound filters, must be either AND or OR

The order of the parameters also matter, but they can be sorted by the numbering ( _subj_, _subj1_, _subj2_ , ... )

For example: /timbr/api/q/timbr_supply_chain/view/person?_subj_=property1&_op_=eq&_comp_=val1&_conj_=AND&_subj1_=property2&_op1_=like&_comp1_=val2&_conj1_=OR_subj2_=property3&_op2_=IN&_comp2_=val2,val3,val4&_subj3_=....

Request:

Querying the customer_view view in the timbr_supply_chain knowledge graph without any filters

curl -X 'GET' \
  'https://timbr-sample.company.com/timbr/api/q/timbr_supply_chain/view/customer_view' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response:

Response code: 200
Response body:

{
  "data": [{...}],
  "executed_query": "SELECT * FROM `vtimbr`.`customer_view`",
  "status": "success"
}

Get config endpoint

Request:

curl -X 'GET' \
  'https://timbr-sample.company.com/timbr/api/get_config/TIMBR_DB_DOMAIN' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response:

Response code: 200
Response body:

{
  "data": {
    "TIMBR_DB_DOMAIN": "jdbc:hive2://172.21.57.160:11000"
  },
  "status": "success"
}

Clear cache endpoint

Important!

Must have a Redis backend set and configured for this endpoint to properly work

Request:

curl -X 'GET' \
  'https://timbr-sample.company.com/timbr/api/clear_cache/timbr_supply_chain' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Response:

Response code: 200
Response body:

{
  "status": "success"
}

Requests and Responses

Examples for calling the REST API endpoints​

Get ontologies endpoint​

Query endpoint​

Get ontology endpoint​

Query concept endpoint​

Query ontology view endpoint​

Get config endpoint​

Clear cache endpoint​

Examples for calling the REST API endpoints

Get ontologies endpoint

Query endpoint

Get ontology endpoint

Query concept endpoint

Query ontology view endpoint

Get config endpoint

Clear cache endpoint