ApiBlaze: Designing the Search API for Properties & Endpoints

ApiBlaze is a tool to explore API specifications: Search for a keyword, filter for objects, properties, or endpoints, and immediately see descriptions and code examples. ApiBlaze helps you to answer a specific question about an API lightning fast. You can try it here: apiblaze.admantium.com.

When searching for API elements, you will find objects, properties and endpoints. When selecting them, they will be displayed differently: objects show their data model, properties a list of ranked objects in which they appear, and endpoints show request parameters as well as complex response objects.

In this article, we will cover the modifications required for displaying properties and endpoints, and finish the ApiBlaze development journey.

This article originally appeared at my blog.

Handling Requests for Loading Details

When the user clicks on a search result, the frontend requests to load the details from the backend. The backend distinguishes which type of object is requested, and calls a specific handler method.

Let’ continue to see how properties are loaded.

Search & Render Properties

For a property, we need its name, description, type, and a list of all objects that use this property. This information is gathered with the following steps:

  • Load the containing object of the property
  • Load the definition of the property inside the containing object
  • Search in all objects if they contain the property, and save all these object names

The resulting data structure is this:

The frontend consumes this structure and creates the following representation:

Search & Render Endpoints

Endpoints are a unique entity that requires special treatment. When an API specification is loaded, the endpoints will be indexed and separated along their HTTP methods. For example, when both GET and POST methods are accepted, two entries will be created. Here is an example:

Both search items reference the same endpoint specification. From this specification, we need to extract the relevant information.

The steps are quite complex, so let’s start from the beginning: The original OpenAPI spec. The post endpoint looks like this:

Endpoints have two interesting pieces of information: parameters and responses.

Processing Endpoint Parameters

Parameters can be passed as query parameters, added to the URLs. Or they can be passed inside the request body as the JSON payload. While query parameters are simple key-value pairs, body parameters are the nested, complex objects that were covered in the last article.

Parameters are processed with these steps:

  1. Filter all parameters which have the property in === 'query'
  • For these items, only store the attributes description and type

2. Filter all parameters if there is a single item with the property in === 'body'

  • For this item, process its nested schema attribute

Applying these transformations to the above mentioned post endpoint leads the following data structure:

Body Parameters and query parameters will be rendered in their own code boxes. As before, the JSON structure will be converted to a string and several HTML transformations will be applied.

Here is an example:

Processing Endpoint Responses

In the original OpenAPI spec, responses are mapping of HTTP status codes to objects with a description and a schema. Here is an example for the status code 200.

The optional element schema points to a nested object which will be processed. The resulting data structure is this:

When rendered, each status code is a separate section with the nested object shown in a code box.

ApiBlaze Project Requirements are Finished

With these changes completed, we have fulfilled all ApiBlaze 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

Conclusion

The ApiBlaze development journey was long and knowledge intensive. Initially prototyped in the middle of 2020, I restarted the project after a long break. The requirements evolved: In addition to core functions, I also wanted to use WebSockets and use a custom framework to deepen my knowledge. Not entirely surprising, developing a framework became journey of its own, and a very rewarding one to deepen JavaScript knowledge. When I read about the other JavaScript frameworks, and see how they are working, I can better relate to the features they have and how they help to design applications. Finally, I’m happy to have completed this journey, and hopefully you will use ApiBlaze to quickly search in API specifications.

IT Project Manager & Developer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store