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

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.

Key Features

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.

Technologies

  • 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.

Requirements

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

Framework

  • FRAME01 — Controller & Routing
  • FRAME02 — Stateful Pages & Components
  • FRAME03 — Actions
  • FRAME04 — Optimized Bundling

Technologies

  • 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.

Conclusion

Footnotes

IT Project Manager & Developer