ApiBlaze: SPAC Framework Refactoring

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.

Having finished the implementation of my custom JavaScript framework SPAC (Statefull Pages, Actions and Components) and exploring OpenAPI specifications and tools in my last two posts, this article continues the ApiBlaze series. I will explain how to refactor the early prototype to a SPAC app.

This article originally appeared at my blog.

Phase 0: Setup

  • Install the spac NPM package
src
└── actions
│ └── SearchApiSpecAction.js
└── components
├── ApiSearchComponent.js
└── ApiSearchResultsComponent.js
└── pages
│ ├── IndexPage.js
│ ├── SearchApiElementsPage.js
└── index.js
  • Create an index.js file with the following content:
import { Controller } from 'spac'const controller = new Controller()controller.init()

The controller starts the app, but since no components, actions or pages are provided, it displays nothing. Lets’ refactor each of these sequentially.

Phase 1: Refactor Components

In the early prototype, components had quite a lot code duplication. By moving to SPAC, this duplication is eliminated, and the remaining code is more compact.

Here is an example of the API search bar component. It includes the redundant functions updateState(), getState() and refresh(). Also, all these functions need to be explicitly exported.

import { handleApiSearch } from '../controller.js'let state = {}
let _$root = undefined
function updateState (newState) {
state = { ...state, ...newState }
console.log('new state', state)
}
function getState () {
return state
}
function render (args) {
const html = `
<h2>Load an API</h2>
<input type="text" class="api-search-bar" id="api-search-bar" value="" spellcheck="false">
<div id="api-search-results" class="api-search-results">
`
return html
}
function mount ($root, ...args) {
_$root = $root
$root.innerHTML = render(args)
document
.getElementById('api-search-bar')
.addEventListener('keydown', e => handleKeydown(e))
// ...
}
function refresh (args) {
mount(_$root, args)
}
export { mount, getState, refresh }

In the refactored component, only two main functions remain: render() and mount(). Other essential methods are all defined in the Component parent class and don't need to be repeated here.

import { Component } from 'spac'export default class SearchBarComponent extends Component {
render = () => {
return `
<h2>Load an API</h2>
<input type="text" class="api-search-bar" id="api-search-bar" value="${this.getState().apiSearchQuery}" spellcheck="false">
<div id="api-search-results" class="api-search-results">
`
}
mount () {
super.mount()
document
.querySelector('#api-search-query')
.addEventListener('keyup', e => this.handleKeyUp(e))
}
}

The basic steps are:

  • Create a class that extends Components

Phase 2: Refactor Actions

Actions are a special case, because there were no similar abstractions in the earlier prototype. Therefore, refactoring means…

  • Identify all external API function calls and calls to the backend

Phase 3: Refactor Pages

In the early prototype, pages had only few responsibilities: Rendering HTML, and mounting the rendered HTML and their component.

Here is the example of the index page.

import { mount as mountSearchBar } from '../components/searchBar.js'function layout () {
const html = `
<section class="search-wrapper" id="search-wrapper">
<h2 id="heading-api-name">Search</h2>
<div id="search-mode"></div>
<div id="search-bar">
<div class="input-wrapper" id="input-wrapper"></div>
</div>
</section>
`
return html
}
function render ($domRoot) {
$domRoot.innerHTML = layout()
mountSearchMode(document.getElementById('search-mode'))
}
export { render }

The refactored version includes the custom constructor function, and the methods render() and mount() are responsible for showing and rendering the HTML.

import { Page } from 'spac'
import ApiSearchBarComponent from '../components/ApiSearchBarComponent.js'
export default class IndexPage extends Page {
constructor (rootDom) {
super(rootDom)
this.addComponents(new ApiSearchBarComponent('#api-search-spec'))
}
render = () => {
return `
<h1>ApiBlaze Explorer</h1>
<section class='api-search-page'>
<div id='api-search-spec' class='api-search-spec'></div>
</section>
`
}
mount () {
super.mount()
document.querySelector('button').addEventListener('click', () => {
// ....
})
return this
}
}

The refactoring steps are therefore very simple:

  • Move the pages HTML to the render() method

Phase 4: Start and Host the Application

Before the application can be used, we need to do one final step: Creating an inventory of the application files, and passing it to the controller.

Add the following command to the script section in the package.json.

"scripts": {
"bootstrap": "node --input-type=module --experimental-modules --eval \"import {bootstrap} from 'spac'; bootstrap('./src')\""
}

Run this command once. Then, modify the index.js to load the inventory file and to pass it in the configuration object to the controller.

import inventory from './inventory.json'const controller = new Controller({ inventory })

Now you can start your application.

Review: ApiBlaze Project Requirements

With the refactoring completed, we have the following status with ApiBlaze requirements:

Searching for APIS

  • ✅ SEA01 — Search for APIs by Keyword

Framework

  • ✅ FRAME01 — Controller & Routing

Technologies

  • ✅ TECH01 — Use PlainJS & Custom Framework

We can now continue with implementing the frontend components, and will start searching for APIs.

Conclusion

This article outlines the refactoring of the early stage ApiBlaze prototype, based on individual JavaScript modules, to a version using the SPAC framework. The first step is the basic setup: Install the npm modules, create directories, add the index.js. Then, one by one, the components, actions and finally pages are refactored. Typically, you move all static HTML to the render() function, and all other DOM manipulations to the mount() functions. The final step is to create an inventory.json file, and then to load this file when creating SPAC controller instance.

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