QMK API

QMK API is a RESTful API that allows you to submit keymap.json files for compilation. Upon a successful compilation the user will be able to download a file that can be flashed directly to their keyboard using a tool like QMK Toolbox.

History

When I started to use QMK the only option for building a custom firmware was to write C. This made it very hard to create your own custom keyboard or keymap, unless you were already familiar with programming. I wanted to make this process easier for both end users and keyboard maintainers.

I set out a few basic requirements for V1:

• Provide all the metadata a web client would need to display a keyboard configuration UI
• Allow a keymap to be submitted for compilation
• The submitted keymaps will have data only, no arbitrary code
• Keymap submition will be decoupled from compilation

Initial Design

My prototype implementation consisted of 4 services:

• API Frontend
• Redis with RQ
• S3-compatible storage
• Compiler Backend

Keyboard metadata (used to render the UI) was gathered by scraping rules.mk (Makefile) and config.h files in the qmk_firmware repository. A webhook that ran on each commit to master would trigger an update job that populated Redis with all the keyboard metadata.

A typical use of the API looks like this:

• User submits a keymap.json
• A compile job is inserted into RQ
• A Compiler Backend picks up the job and compiles the firmware
• The results are uploaded to S3
• The user is notified the job is complete
• The user downloads the resulting firmware from S3

Building Community

Once I had developed this API enough to be used Jack Humbert built a Single Page Application that utilitized it. Soon we launched QMK Configurator and began to promote its use. We were soon joined by Yan-Fa Li who took over development of QMK Configurator and migrated it to Vue piece by piece. Configurator also drove people to improve the metadata for keyboards in QMK, and in particular James Young stepped up to ensure that every keyboard had a full and complete set of metadata files.

As the primary developer for the QMK API I worked with everyone here, and more, to grow and evolve QMK API and increase access to advanced keyboard features.

Evolution

Like any good project QMK API has both grown in capability and streamlined itself over the years. Here is a short list of the ways I have evolved it:

• Added info.json support for metadata not available in scraped files
• Moved processing of metadata from qmk_compiler repo to qmk_firmware repo to allow for rapid evolution
• Moved metadata storage out of Redis and into a static site backed by a CDN. This change reduced the time it took to switch keyboards from seconds to milliseconds.
• Built out operational tools for managing the queue during times of heavy load