How software talks to software
"Does it have an API?" is the most common integration question on a show, and the words in it get used loosely enough that the answer often means nothing. Three terms, kept apart.
The three words
Protocol, API, SDK
A protocol is what goes over the wire. It is an agreement about bytes: what a message looks like, in what order, on which port. OSC, sACN, MIDI and HTTP are protocols. Two devices that speak the same protocol can exchange data without either knowing anything else about the other.
An API — application programming interface — is the published contract for talking to a specific piece of software. It says which requests you are allowed to make, what each one does, and what comes back. An API is usually carried over a protocol: QLab's API is carried over OSC; showstack's API is carried over HTTP.
An SDK — software development kit — is a library you install to save yourself writing the API calls by hand. It speaks the API for you and gives you functions in your own language instead. An SDK is a convenience; the API is the thing that actually defines what is possible.
- "It speaks OSC" is not an answer. OSC is a way of formatting messages, not a set of them. Two OSC devices with no shared message list have nothing to say to each other.
- An SDK in the wrong language is not an SDK for you. A Python SDK does not help a show-control system that scripts in Lua — but the underlying API will.
- Undocumented does not mean unusable. The X32 OSC implementation is not formally published and a whole generation of show tooling is built on the community documentation of it. Treat that behaviour as reported, not guaranteed.
- An API can be read-only. Being able to query a device is not the same as being able to drive it, and riders rarely distinguish.
The other question to ask
Does it poll, or does it push?
Once an API exists, the next thing that decides whether an integration feels good is how you find out something changed.
Polling means asking repeatedly: "has anything changed? has anything changed?" It is simple, works through almost any network, and is always either too slow or too wasteful — the interval is a compromise between latency and load.
Push means subscribing once and being told when something happens, over a persistent connection like a WebSocket, or by the device simply broadcasting state the way sACN does. Lower latency, far less traffic, and it needs a connection that stays open.
For anything a cue depends on, you want push. Polling a media server every 500 ms to find out whether a clip ended is how a cue lands late.
What polling actually costs
A worked example
What showstack's own API looks like
This site is a useful example because it is deliberately as simple as an API gets. There is no key, no login, no rate limit and no SDK required: every collection is one file of JSON at a fixed URL, served with permissive CORS so a browser can fetch it directly.
That means any tool — a console macro, a spreadsheet, a media server script, another website — can ask for the data and get it. It also means the entire "API" fits in one line of documentation, which is the point.
- Static JSON is an underrated API. No server to fall over, cacheable at the edge, and it works from a file on a USB stick backstage with no network at all.
- CORS is what makes it usable from a browser. An API without it can only be called from a server, which rules out every in-page tool.
- Versioning in the path (
/v1/) is a promise. It says the shape of this data will not change under anything already built on it.
The full dataset is at /api/v1/index.json under CC BY 4.0 — no key, no rate limit. If you build something on it, say so on the repo and it goes on the list.
- What is an API?
- What is an SDK?
- Poll or push?
Where to go next
These pages are a chain rather than a library — the next one along usually answers the question this one raised.
Everything on this page, in the index
Each of these has its own entry with sources, ports, gotchas and an open gap where a field is missing.