Introduction
In the constantly changing digital ecosystems, millions of developers globally rely on REST APIs to power their applications, streamline data integration, and foster interoperability across systems. Given the vastness and complexity of these API-driven ecosystems, there’s a clear demand for comprehensive API documentation systems. That’s where OpenAPI spec and Swagger have emerged as an essential asset, offering clarity and ease in navigating the multitude of REST API functionalities.
In this blog, we dive deep into the fascinating world of OpenAPI and Swagger, highlighting the self-documenting Swagger UI in Timbr’s semantic graph platform (OpenAPI 3.0 spec), which transforms and redefines the user’s experience when dealing with the vastness and complexity of APIs thanks to Timbr’s Semantic Model put in place.
Unraveling Swagger
Swagger (tools implementing OpenAPI specification) is not just a tool. It’s an entire framework dedicated to the design, building, documentation, and consumption of RESTful APIs. But why is it garnering such attention?
- Who Uses It? From software developers crafting web applications to data scientists in need of seamless API integration, Swagger has found its admirers across the board.
- What Makes It Special? Swagger’s standout feature is its interactive documentation. Gone are the days when developers had to sift through hundreds of pages of API documentation. With Swagger UI, users can visualize and interact with the API’s resources without diving deep into its intricacies.
With this understanding of Swagger’s significance, let’s delve into how it uniquely integrates with Timbr.
Swagger Meets Semantic Models in Timbr: The Perfect Blend
At its core, Timbr isn’t just a semantic graph platform. It’s the bridge connecting disparate data sources, binding them to a user-defined semantic data model rich with relationships. Whether you’re a business analyst leveraging data through business intelligence tools or a data scientist using Python, Scala, or R, Timbr ensures your data is ready to be integrated, modeled, and consumed, without any hurdles.
Enter Swagger UI into Timbr. This new feature isn’t just a fancy add-on; it’s a vital REST API gateway.
How? Let’s find out.
A Dynamic Duo: Swagger of a Semantic Model
While Swagger itself is a commendable tool, what makes its incorporation into Timbr truly revolutionary is its REST API self-documenting nature above the semantic models.
Imagine constructing a complex knowledge graph with intricate connections and multifaceted nodes. As time progresses, this graph evolves – new connections emerge, nodes get updated, and the complexity grows. Traditionally, every such update would require manual documentation and update to the API layer, carefully listing every change. But with Timbr’s Swagger, there’s no manual labor after each and every update.
Every creation and every minute update made to the knowledge graph is automatically displayed within the Swagger UI. The implications?
- Consistent and Updated Information: No lag, no outdated manuals. Every change is immediately reflected, ensuring users always have the latest data schema at their fingertips.
- Efficiency and Speed: No more waiting for manual documentation to catch up. Swift updates mean users can immediately utilize the latest versions for their applications or analyses.
- User Empowerment: App developers, data scientists, or anyone interacting with the REST API can now seamlessly understand the data’s structure, relationships, available filters, and operations like “GET” and “POST”. Everything is laid bare in an intuitive, user-friendly manner.
Unleash the Power of Self-Documenting Semantic APIs
Additional Capabilities that Set Timbr Apart
Beyond the inherent API self-documenting attributes of the semantic models mentioned above, which streamline user comprehension and reduce manual interventions and lag times, Timbr introduces a set of distinctive features. These innovations uniquely position Timbr’s Swagger UI in a league of its own.
So what are those features?
Auto-generated REST Endpoints
Based on the user’s knowledge graph model, REST endpoints are automatically generated for each concept or ontology view. This implies that for every concept you model in your knowledge graph, there’s a corresponding endpoint in the Swagger UI. (as shown in the following images)
Knowledge Graph Model Concepts
Corresponding endpoints in the
Swagger UI
What’s even more convenient? If you want to dig deeper or refine your queries, the UI supports optional filters on properties that can be easily incorporated as query parameters. The intuitive design allows even those unfamiliar with knowledge graphs to effortlessly query endpoints right from the Swagger UI.
Property Filters as Query parameters
Paging Through Results With Limit and Offset
Managing large sets of data results has never been easier, thanks to Timbr’s implementation of pagination support in its REST API. When querying collections of resource results, you’ll notice consistent paging patterns across all URLs.
Here’s a quick summary for those unfamiliar:
Limit: This parameter defines the maximum number of items returned in a single request, effectively setting your page size. While the default limit is set to 15 results per request, users can adjust it up to a maximum of 100.
Offset: This is your navigator. It defines the starting point within your collection. As an example, if you’re dealing with a collection of 15 items and set a limit of 5, you can retrieve all items over three successive requests: the first with offset=0 (to start from the beginning), followed by offset=5 and finally offset=10.
With these tools at your disposal, managing and navigating through extensive data collections becomes straightforward and efficient.
Limit & Offset parameters
Nested Query Capabilities
Timbr’s Swagger API endpoints supports nested queries and efficient traversal of interconnected data structures, improving query performance and reducing network overhead.
Let’s delve into some visual examples to bring the above concepts to life. Accompanying this section, you’ll find three examples that represent distinct query executions in Swagger. To see further examples and learn more about how Timbr automatically nests results (JSON), please refer to our previous article that discusses how Timbr’s REST API and nested results power apps.
Example 1 – Non-nested Query
The first example and image showcase a simple, non-nested query executed via the Swagger UI exemplifying how straightforward it is to pull data.
We are simply querying our Knowledge graph view called order_details, which is built upon our concept order, where Nested is set to False.
The View in Timbr looks as follows:
SELECT
`entity_id`,
`order_id`,
`market`,
`order_city`,
`order_country`,
`order_profit`,
`ordered_by[customer].entity_id`,
`ordered_by[customer].customer_name`,
`ordered_by[customer].customer_id`,
`in_shipment[shipment].entity_id`,
`in_shipment[shipment].shipment_id`,
`in_shipment[shipment].shipping_date`,
`in_shipment[shipment].shipping_mode`
FROM `dtimbr`.`order`
The Query of the View in Swagger with Nested turned off looks as follows (press on image to expand):
Example 2 – Nested Query (Concept Level)
The second example and image dive deeper, illustrating a nested query that zeroes in on a specific concept within the knowledge graph.
Once again, we are querying the same Knowledge graph view above that makes use of concept order, however, now Nested is set to True.
The query in Swagger looks as follows (press on image to expand):
Example 3 – Nested Query (View level with filter)
Finally, the third example and image go one step further. This query filters a property from a concept in the knowledge graph, allowing for precise data extraction.
In this case, we once again chose our view called order_details which queries the concept order, and we chose to use the property order_id, specifically asking for order_id = 10356.
After clicking on Execute, the query in Swagger looks as follows (press on image to expand):
These visual representations serve as a testament to the versatility and depth Timbr’s Swagger UI provides to its users, making complex data interactions feel uncomplicated.
Conclusion:
As digital boundaries expand and data ecosystems become increasingly complex, tools that promise simplicity, efficiency, and accuracy will emerge as champions. Timbr.ai’s commitment to these principles is always evident, as well as in this case with its integration of a self-documenting Swagger UI above all semantic layers.
It’s not just about making data access easier; it’s about crafting a seamless, dynamic, and empowering user experience. As we journey forward, we invite you to be a part of this revolution, experiencing firsthand the power of a truly integrated semantic model with Swagger.
