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/create_ontology/`	`POST`	`{ ontology_name: <new_ontology_name> }`	Creates a new ontology in the timbr
`/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"
}

Create ontology endpoint

Assuming the new ontology name we want to create is timbr_finance

Request:

curl -X 'POST' \
  'https://timbr-sample.company.com/timbr/api/create_ontology' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -d '{ 
  "ontology_name": "timbr_finance"
}'

Response:

Response code: 200
Response body:

{
  "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 P OR
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"
}

Examples for calling the REST API endpoints​

Get ontologies endpoint​

Query endpoint​

Get ontology endpoint​

Create 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

Create ontology endpoint

Query concept endpoint

Query ontology view endpoint

Get config endpoint

Clear cache endpoint