ApiBlaze: A new Developer Journey
ApiBlaze is my new project, and this is the first post in a developer journal series — a set of related posts that cover individual aspects of the design, implementation and technologies. In this very first article, I explain the motivation, the key features, technologies and requirements to start the realization of ApiBlaze.
This article originally appeared at my blog.
Why I started ApiBlaze
The project’s motivation was sparked during my ongoing work with Kubernetes in deploying a complex microservice application.
When working with Kubernetes’ complex YAML files, you often need to double check where specific data objects need to be put. Finding this in the official documentation is not always easy. So, I took a look at the extensive API specification available in OpenAPI format. You can see the original JSON specification, or head over to HTML documentation. This, however, is not searchable at all — you need to know exactly at which endpoint to look to see how to structure a data model.
All in all, I could not quickly find what I was looking for: A compact representation of the data model. Can this be done better? Can I not simply search with keywords to see only the currently relevant parts?
Providing a simple keyword-based search and seeing a compact representation of the data model is the main motivation for my ApiBlaze project.
When you load ApiBlaze, you see a single search bar — and buttons for the most recently requested APIs. You type in a few keywords, and a popup opens with the APIs that best matches your search word. You can navigate with arrow keys to scroll down or up the search results. When you click on any search result in the popup, or when you press ‘Enter’ in the search bar, the selected API will be loaded.
The next screen consists of three sections: The search bar section, the description, and the code example section.
In the first section, you see a search bar for API elements. A set of radio buttons let you choose which specific element you are searching for: An object, property, endpoint, or for everything, including keywords in elements descriptions. Interactions with this API element search bar stay the same: A popup shows the best matching result, you select an entry using arrow keys and enter or click on any item.
In the description section, you will see a compact and comprehensive representation of the selected element: Its name, its type, its description text.
The code example section is context-specific. If you select an object, you will see its entire data model. If you select a property, you will see this properties’ definition, and a list of all element in which this element occurs. Finally, if you select an endpoint, you will see its request and its response object structure. The specific context will be further highlighted to explain what you selected. All code examples can be copied on a click.
The key feature during all interactions with ApiBlaze is immediate feedback. Whether you search for API specifications or API elements, a single key stroke changes the displayed information blazingly fast.
- PlainJS: To enable powerful visualizations, I want to work close to the DOM with PlainJS1. For styling, I will structure the CSS using SAAS.
- WebSockets: The application consists of a backend that holds the API specification, data model and search functions, and the frontend with the above explained sections. In order to achieve “blazingly fast” interactions, backend and frontend will be connected with WebSockets, a technology to enable long-lasting, full-duplex connections between two endpoints to stream data.
In my other projects, it helped me a lot to make a list of all the requirements that I want to achieve. This list is at the same time an ordered guideline what to do, and it helps me to see the projects overall progress.
For ApiBlaze, I want to realize the following requirements:
Searching for APIS
- SEA01 — Search for APIs by Keyword
- SEA02 — Show search results in a popup
- SEA03 — Select a search results with arrow keys, enter and mouse click
Searching API Elements
- SEL01 — Distinguish objects, properties and endpoints
- SEL02 — Search for API Elements by keywords
- SEL03 — Show search results in a popup
- SEL04 — Select a search results with arrow keys, enter and mouse click
Display API Elements
- DIS01 — Show an objects description
- DIS02 — When an object is selected: Show its entire data model
- DIS03 — When a property is selected: Show in which objects it is used
- DIS04 — When an endpoint is selected: Show its request and response object
- FRAME01 — Controller & Routing
- FRAME02 — Stateful Pages & Components
- FRAME03 — Actions
- FRAME04 — Optimized Bundling
- TECH01 — Use PlainJS & Custom Framework
- TECH02 — Use SAAS for CSS
- TECH03 — Use WebSockets to Connect Frontend and Backend
At the time of writing this article, the requirements do not cover what I call “advanced visualizations”, additional helpful interactions to get all required information from an API specification. I allow myself the freedom to add them later.
This article introduced ApiBlaze, my ongoing development projects that enables searching in OpenAPI specifications for data objects, properties and endpoints. I explained my main motivation, the key features and technologies I want to use. In the final section I made a list of essential requirements that serve to structure my project.