Introduction
REST API and GraphQL are the popular options that developers use to retrieve data for websites and web applications. In the past few years, REST emerged as the preferred alternative for building scalable applications, however, REST APIs have proven too rigid to adapt to the dynamic demands of accessing clients.
GraphQL is a query language that provides greater flexibility and efficiency for data retrieval, dealing with shortcomings that developers experience when using REST APIs, while posing several weaknesses that make it too complex for some use cases.
Timbr REST API leverages on the capabilities of the SQL semantic graph platform to power data consumption in applications. Timbr REST API users benefit from simplified data access to one or more data sources, data integration, relationships, results nesting, expressive querying and enhanced security. These benefits ultimately lead to rapid development, improved performance, and easier maintenance of REST API applications.
Timbr REST API
Features
The following table describes the main features of Timbr REST API and how it compares to GraphQL and REST:
Advantages
- Simplified Data Access: Timbr REST API draws data from one or more data sources by means of the semantic layer concepts that represent and unify data, so developers benefit from simplified data access.
- Data Fetching: Timbr REST API allows clients to specify exactly which fields they need in a single request, avoiding over-fetching or under-fetching of data, same as GraphQL.
- Data Nesting: Timbr REST API allows clients to fetch nested data structures from multiple data entities in a single request, enabling efficient data retrieval. This reduces the size of the result and the number of round trips required to fetch related data, improving efficiency. GraphQL provides similar functionality.
- Relationship Handling: Similarly to GraphQL, Timbr REST API excels in handling complex relationships between data entities. It provides mechanisms to traverse relationships, perform filtering, and specify related data to include in the response. By incorporating relationship handling features, the Timbr REST retrieves interconnected data efficiently.
- Performance: Timbr REST API delivers high performance, providing query optimization when data is nested and fetched in a single call, reducing network payload.
- Learning Curve: GraphQL requires learning of the query language’s syntax and logic. Timbr REST can be accessed by leveraging SQL or simple REST URL filters.
- Security: Timbr permission management allows managing users and resources permissions with role-based access control and row-level access control for enhanced security.
- Use cases: Timbr REST API can be used in any type of application and excels in complex queries. GraphQL is used in applications requiring rapidly changing data, complex systems and microservices but is not apt for complex queries.
- Self Documenting: Self-documenting Swagger UI.
Endpoints
Timbr offers a number of endpoints to expose data and manage the semantic layer according to the user’s preferences. The complete list can be found in this page. The endpoints to request data are shown in the table below and include an option for querying in SQL and two options that use endpoint filters.
Examples
In the following examples we show how Timbr REST API retrieves data about users and the posts they created. There are two tables, one for users (name, age, email) and another for posts (title, content and date published).
There are two possible starting points for a user. In the first, data is already modeled as part of a semantic graph layer in use by the enterprise:
The specific data needed for our app is represented by two concepts in this ontology (user and post). Timbr admins can provide users with specific access to this data (granularly up to row level access) for security and privacy purposes.
In the second option, a user starts from database tables, and models data specifically for the app as a semantic graph following the guidelines found here:
Note that the shareable semantic graph model provides unified meaning of data, consistent metrics and includes the definition of relationships that substitute JOINs to facilitate querying the data. This key advantage of the semantic graph is leveraged by the Timbr REST API.
Once we select our data model, we are ready to proceed to use either one of the endpoints in Table 2 above.
Example 1 – Non-nested and nested requests using View endpoint
Non-Nested Request
Call: users name, email and posts (including title and content) for users aged 25.
We first create a view in Timbr to be used as our query endpoint:
CREATE OR REPLACE ONTOLOGY VIEW users AS
SELECT entity_id, name, email, created[post].entity_id, created[post].title, created[post].content FROM dtimbr.user
WHERE created[post].published = TRUE
Now we create our request using the View endpoint, taking advantage of one of many available filters.
GET /timbr/api/q/user_network/view/users?_subj_=age&_op_=eq&_comp_=25
Host: example.com
Content-Type: application/json
x-api-key: tk_639b06…..
Non-Nested Response
{
"data":
[
{
"entity_id": "881",
"name": "John Doe",
"email": "john.doe@example.com",
"created[post].entity_id": "p_123151",
"created[post].title": "Timbr: Unleashing the Power of Semantic Knowledge Graphs",
"created[post].content": "Timbr is a cutting-edge platform that harnesses the potential of semantic knowledge graphs. It allows users to explore and uncover insights from interconnected data, enabling smarter decision-making and efficient data-driven workflows."
},
{
"entity_id": "881",
"name": "John Doe",
"email": "john.doe@example.com",
"created[post].entity_id": "p_123152",
"created[post].title": "Understanding Complexity with Timbr Knowledge Graph",
"created[post].content": "Timbr semantic knowledge graph offers a powerful solution for comprehending complex relationships between diverse data elements. By visualizing and analyzing these connections, Timbr empowers users to gain a deeper understanding of intricate systems and make informed decisions."
},
{
"entity_id": "882",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"created[post].entity_id": "p_733024",
"created[post].title": "Enhancing Data Integration and Discovery with Timbr Knowledge Graph",
"created[post].content": "Practical examples of using Timbr in real-world applications"
}
],
"status": "success"
}
Nested Request
To get a nested response we only need to add the header “nested: true” to the same previous request:
GET /timbr/api/q/user_network/ view/users?_subj_=age&_op_=eq&_comp_=25
Host: example.com
Content-Type: application/json
x-api-key: tk_639b06…..
nested: true
Nested Response
{
"data": [
{
"entity_id": "881",
"name": "John Doe",
"email": "john.doe@example.com",
"created[post]": [
{
"entity_id": "p_123151",
"title": "Timbr: Unleashing the Power of Semantic Knowledge Graphs",
"content": "Timbr is a cutting-edge platform that harnesses the potential
of semantic knowledge graphs. It allows users to explore and uncover insights from interconnected data, enabling smarter decision-making and efficient data-driven workflows."
},
{
"entity_id": "p_123152",
"title": "Understanding Complexity with Timbr Knowledge Graph",
"content": "Timbr semantic knowledge graph offers a powerful solution for comprehending complex relationships between diverse data elements. By visualizing and analyzing these connections, Timbr empowers users to gain a deeper understanding of intricate systems and make informed decisions."
}
]
},
{
"entity_id": "882",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"created[post]": [
{
"entity_id": "p_733024",
"title": "Enhancing Data Integration and Discovery with Timbr Knowledge Graph",
"content": "Practical examples of using Timbr in real-world applications"
}
]
}
],
"status": "success"
}
Unlock the power of Timbr REST API
Comparison to GraphQL
For comparison, we show the process to request the same data using GraphQL.
Schema creation
type User {
id: ID!
name: String!
email: String!
posts(filter: PostFilter): [Post!]!
}
type Post {
title: String!
content: String!
published: Boolean!
}
input UserFilter {
age: Int
}
input PostFilter {
published: Boolean
}
type Query {
users(filter: UserFilter): [User!]!
}
GraphQL Query
POST /graphql HTTP/1.1
Host: example.com
Content-Type: application/json
{
"query": "query {
users(filter: { age: 25 }) {
id
name
email
posts(filter: { published: true }) {
title
content
}
}
}"
}
Response to GraphQL Query
{
"data": {
"users": [
{
"id": "881",
"name": "John Doe",
"email": "john.doe@example.com",
"posts": [
{
"title": "Timbr: Unleashing the Power of Semantic Knowledge Graphs",
"content": "Timbr is a cutting-edge platform that harnesses the potential of semantic knowledge graphs. It allows users to explore and uncover insights from interconnected data, enabling smarter decision-making and efficient data-driven workflows."
},
{
"title": "Understanding Complexity with Timbr Knowledge Graph",
"content": "Timbr semantic knowledge graph offers a powerful solution for comprehending complex relationships between diverse data elements. By visualizing and analyzing these connections, Timbr empowers users to gain a deeper understanding of intricate systems and make informed decisions."
}
]
},
{
"id": "882",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"posts": [
{
"title": "Enhancing Data Integration and Discovery with Timbr Knowledge Graph",
"content": "Practical examples of using Timbr in real-world applications"
}
]
}
]
}
}
Example 2 – Nested request using SQL query endpoint
This option leverages on the expressiveness and relationships of SQL querying of the semantic layer:
POST /timbr/api/query HTTP/1.1
Host: example.com
Content-Type: application/json
x-api-key: tk_183d0f75….
{
“ontology_name”: “user_network”,
“query”: “SELECT entity_id, name, email, created[post].entity_id, created[post].title, created[post].content FROM dtimbr.user WHERE age = 25 AND created[post].published = TRUE”
}
Nested Response
We get the same nested response as in Example 1:
{
"data": [
{
"entity_id": "881",
"name": "John Doe",
"email": "john.doe@example.com",
"created[post]": [
{
"entity_id": "p_123151",
"title": "Timbr: Unleashing the Power of Semantic Knowledge Graphs",
"content": "Timbr is a cutting-edge platform that harnesses the potential
of semantic knowledge graphs. It allows users to explore and uncover insights from interconnected data, enabling smarter decision-making and efficient data-driven workflows."
},
{
"entity_id": "p_123152",
"title": "Understanding Complexity with Timbr Knowledge Graph",
"content": "Timbr semantic knowledge graph offers a powerful solution for comprehending complex relationships between diverse data elements. By visualizing and analyzing these connections, Timbr empowers users to gain a deeper understanding of intricate systems and make informed decisions."
}
]
},
{
"entity_id": "882",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"created[post]": [
{
"entity_id": "p_733024",
"title": "Enhancing Data Integration and Discovery with Timbr Knowledge Graph",
"content": "Practical examples of using Timbr in real-world applications"
}
]
}
],
"status": "success"
}
Conclusion
The Timbr REST API is a powerful and flexible solution for modern application development. Its innovative approach brings the best of the traditional REST APIs and GraphQL .
Timbr delivers key benefits to REST API applications, with simplified data access through its semantic graph layer, enabling developers to access data from multiple sources effortlessly. It supports nested queries and efficient traversal of interconnected data structures, improving query performance and reducing network overhead.
Timbr also helps manage schema evolution and versioning, providing mechanisms for defining and maintaining schemas at a higher level of abstraction, allowing gradual changes and maintaining backward compatibility.
Additionally, the Timbr REST API offers metadata and documentation features, providing valuable information about entities, relationships, and attributes, thereby enhancing the developer experience and promoting better collaboration.
Want to reduce network overhead of your app
with Timbr REST API?
How do you make your data smart?
Timbr virtually transforms existing databases into semantic SQL knowledge graphs with inference and graph capabilities, so data consumers can deliver fast answers and unique insights with minimum effort.
