docs/api_development_overview.md at master

keyboard stuff
qmk_firmware / docs / api_development_overview.md
at master 44 lines 2.2 kB view raw view rendered
wrap content
 1# QMK Compiler Development Guide
 2
 3This page attempts to introduce developers to the QMK Compiler. It does not go into nitty gritty details- for that you should read code. What this will give you is a framework to hang your understanding on as you read the code.
 4
 5# Overview
 6
 7The QMK Compile API consists of a few moving parts:
 8
 9![Architecture Diagram](https://raw.githubusercontent.com/qmk/qmk_api/master/docs/architecture.svg)
10
11API Clients interact exclusively with the API service. This is where they submit jobs, check status, and download results. The API service inserts compile jobs into [Redis Queue](https://python-rq.org) and checks both RQ and S3 for the results of those jobs.
12
13Workers fetch new compile jobs from RQ, compile them, and then upload the source and the binary to an S3 compatible storage engine.
14
15# Workers
16
17QMK Compiler Workers are responsible for doing the actual building. When a worker pulls a job from RQ it does several things to complete that job:
18
19* Make a fresh qmk_firmware checkout
20* Use the supplied layers and keyboard metadata to build a `keymap.c`
21* Build the firmware
22* Zip a copy of the source
23* Upload the firmware, source zip, and a metadata file to S3.
24* Report the status of the job to RQ
25
26# API Service
27
28The API service is a relatively simple Flask application. There are a few main views you should understand.
29
30## @app.route('/v1/compile', methods=['POST'])
31
32This is the main entrypoint for the API. A client's interaction starts here. The client POST's a JSON document describing their keyboard, and the API does some (very) basic validation of that JSON before submitting the compile job.
33
34## @app.route('/v1/compile/&lt;string:job_id&gt;', methods=['GET'])
35
36This is the most frequently called endpoint. It pulls the job details from redis, if they're still available, or the cached job details on S3 if they're not.
37
38## @app.route('/v1/compile/&lt;string:job_id&gt;/download', methods=['GET'])
39
40This method allows users to download the compiled firmware file.
41
42## @app.route('/v1/compile/&lt;string:job_id&gt;/source', methods=['GET'])
43
44This method allows users to download the source for their firmware.