XRTC – APIs Documentation
XRTC is a lightning fast real time streaming protocol.
We designed it to be as simple as possible to use for all developers, newbies to experienced alike.
If you have any questions or need help, you can ask us on Twitter or join our Discord or Reddit or simply email us.
For technical support and bug reporting, you can contact our nearly 24/7 monitored tech support.
Remember to check out our open source repository for libraries and examples on how to use XRTC, and also for a constantly updated, in-depth, technical version of the docs.
We also have a ready to use XRTC pip module for Python ready to use.
In a nutshell
To use XRTC, you have to get an API key and related account id from our website.
Once you do that, you need to login your API key, thus getting a cookie that you can use to transfer data.
A basic, SDK-free Python implementation that sends and gets data through an "example" portal looks like this:
import requests
import json
accountId = "AC1234567898765432"
apiKey = "aaabbbcccdddeeefffggghhhiiijjj"
payload = "hello, world"
loginURL = "https://api.xrtc.org/v1/auth/login"
setURL = "https://api.xrtc.org/v1/item/set"
getURL = "https://api.xrtc.org/v1/item/get"
loginRequestData = {"accountid": accountId, "apikey": apiKey}
setRequestData = {"items": [{"portalid": "example", "payload": payload}]}
getRequestData = {"portals": [{"portalid": "example"}]}
with requests.Session() as session:
session.post(loginURL, json.dumps(loginRequestData))
session.post(setURL, json.dumps(setRequestData))
responseGet = session.post(getURL, json.dumps(getRequestData))
print(json.loads(responseGet.content))
That's it. Just keep your payloads under 1 KB per request. That's how easy it is.
And if you use our SDK, it's even simpler!
Now for the more detailed version.
How does XRTC work
XRTC is a TCP streaming protocol based on standard http POST requests. Contrary to popular belief, this is the most efficient and fastest way to live stream data across the internet.
We provide the backend to use XRTC for free for up to one million 1Kb requests per month. If you need more than that, paid plans are available on request. If you want to host your own XRTC server, that's also a paid feature.
Before using our public APIs, remember to read our terms of service!
The API keys
The first thing you need to use XRTC is an API key. You can just go to our website to get one.
The first time you receive any API key you get assigned an account id. Store both of them in a secure way: anybody with access to these can read all of the data you send through the API.
Registering for an API key requires a valid, working, non disposable email address.
Every user gets up to 10 API keys to be used in parallel, valid indefinitely. Beyond this limit, the oldest API is overwitten by a new one.
Log in
In order to use the API key, you first have to authenticate it with your account id. This is done by sending a POST request (ideally managed by our SDK):
Request URL: https://api.xrtc.org/v1/auth/login
Request data: {"accountid":"AC################", "apikey":"################################"}
If successful, the response will contain a timestamp:
Response: {"servertimestamp":1659716661000}
This timestamp can be used for syncing purposes between clients or for measurement purposes.
The response will also contain a JSESSION cookie, to be used with further data transfer requests. If the cookie is not used for longer than one minute, the login process has to be repeated.
If unsuccessful, typical errors are:
- 30: Invalid arguments (wrong argument name or type or value)
- 35: Invalid credentials (wrong account id or API key)
- 45: Login called too often for this API key
Sending data
After logging in and getting the JSESSION cookie, you can start sending data.
When sending data, you can provide a string up to 16 characters long that will identify your data stream, a "portal" id in XRTC parlance. Every API key can have up to 10 portals active.
The payload is passed as a string (a json dump of a dictionary or class will do the trick), with maximum overall size of 1KB per request. There is a ring buffer on the server of the size of 10 items per portal. If the size of the supplied array exceeds the buffer size, only the first 10 items will be used.
The newest incoming items will overwrite the oldest items in the buffer – keep that in mind when balancing get and set rates.
The data sending is done by POST request (ideally managed by our SDK) along with the login JSON cookie:
Request URL: https://api.xrtc.org/v1/item/set
Request data: {"items":[{"portalid":"abc", "payload":"xxx"},{...}]}
If the request is valid, the response is:
Response: {"servertimestamp":################}
Typical errors are:
- 20: Invalid arguments (wrong argument names or payload size exceeded)
- 30: Invalid arguments (wrong argument values)
- 10011 or 401: Server session denied (wrong or expired JSESSION cookie)
Getting data
After getting the JSESSION cookie, you can also start receiving data.
To receive data you need to provide an optional portal id from which you want to get the data from; if you do not specify a portal, data for all portals for this accountid will be sent, up to the size limit for the request.
The data retrieving is done by POST (again, ideally managed by our SDK) request along with the login JSON cookie:
Request URL: https://api.xrtc.org/v1/item/get
Request data:
{portals:[{"portalid":"abc","mode":"probe","schedule":"LIFO","cutoff":"100"}]}
or: {portals:[{"portalid":"abc"}]}
or: {portals:[]}
The successful response being:
Response: {items:[{"portalid":"abc","payload":"#####","servertimestamp":#######"},{...}]}
There are three very useful optional arguments: mode, schedule, cutoff.
Mode, for fine tuning how often data should be returned, has three settings possible:
Schedule, for deciding what items should be returned first:
Cutoff, defines time in ms for the maximum age of the items to be served.
A value of -1 (default) will return all items available, regardless of age.
For small tests or low power IoT purposes, probe can be used to just get data back sporadically. Watch can be used for more data intensive applications, such as PTZ remote control for a camera. Stream is for when latency requirements are the strictest and/or data flows are the largest.
LIFO and FIFO can then help you make sure you don't lose any data if get rate is not very high, while cutoff can help you avoid having stale data sent when a portal is reused after a pause or if you have to catch up with some buffering.
Typical errors are:
- 20: Invalid arguments (wrong argument names)
- 30: Invalid arguments (wrong argument values)
- 10011 or 401: Server session denied (wrong or expired JSESSION cookie)
Other
As you can see, XRTC is designed to be dead simple to use. Data goes in, data goes out.
Our XRTC API is work in progress, so expect more features and the current limitations to be constantly raised over time; the basic calls will however always remain the same, because we believe simple things should stay simple.
If you want to measure how much latency XRTC is adding, you can ping ping.xrtc.org to get the baseline.
Our open source repository has reference implementations for a number of languages and example projects, and it's constantly updated with new ones, so keep an eye on it.
We can't wait to see your amazing projects built with XRTC!
