QM's Application Programming Interface (API) uses JavaScript Object Notation (JSON) as its common data interchange format and Hypertext Transfer Protocol (HTTP) as its communications protocol. It also supports Cross-Origin Resource Sharing.
This table specifies the "routes" understood by QM's API server. Request and
response data use JSON format, but data may be omitted where values are left
blank. JSON objects are denoted {}
, and JSON arrays are denoted []
.
HTTP Request | HTTP Response | ||||
---|---|---|---|---|---|
Purpose | Method | URL | Data | Code | Data |
Get avar | GET | /box/cardboard?key=982770f29 | 200 | {} |
|
Get list | GET | /box/cardboard?status=waiting | 200 | [] |
|
Set avar | POST | /box/cardboard?key=982770f29 | {} |
201 |
The data model is based on Quanah_'s asynchronous variables ("avars"). An avar is a JavaScript object that acts as a generic container for other types by storing data in its "val" property. QM extends this model by adding "box", "key", and optional "status" properties. The "box" property is useful for grouping avars in various ways, while the "key" property is a unique identifier for each avar. The optional "status" property is present on avars that represent job descriptions.
To get the value of an avar, a client must request it by known box and known key. For the example shown in the table, an avar with "cardboard" as its box, "982770f29" as its key, and 2 as its value would look like
{"box":"cardboard","key":"982770f29","val":2}
Because job descriptions are avars that must be accessed by a known box and a known key, a volunteer which knows only the box cannot run a job until it also knows the job's key. Clients may request a list of jobs' keys using a known box and a known status; this list is represented as a JSON array. For the example shown in the table, an array containing three avars' keys might look like
["job_key_1","job_key_2","job_key_3"]
To set the value of an avar, a client must send the new value in a request by known box and known key. No response data will be returned, but a successful response will be indicated by an HTTP status code of 201.
The latest version of the API (|release|) includes extensions that enable versioned API calls. These routes were added in anticipation of future needs to support legacy APIs without running legacy servers. Although deprecating the word "box" in favor of "v1" seems desirable, it is possible that it anticipates needs that will never arise in practice. Discussion and input here would be much appreciated.
HTTP Request | HTTP Response | ||||
---|---|---|---|---|---|
Purpose | Method | URL | Data | Code | Data |
Get avar | GET | /v1/cardboard?key=982770f29 | 200 | {} |
|
Get list | GET | /v1/cardboard?status=waiting | 200 | [] |
|
Set avar | POST | /v1/cardboard?key=982770f29 | {} |
201 |