Before I begin, the purpose of this post is not to denigrate the work done by the OpenSky Network team, it's just a list of potential
improvements to the API, as they come to my mind.
* Documentation update *
Currently, the documentation refers to features that no longer exist. Like the /tracks endpoint.
=> Suggestion: As the documentation is generated with Sphinx, make available a repository containing the documentation on
GitHub, use GitHub Actions to generate the documentation (github.com/marketplace?type=actions&query=sphinx),
and GitHub Pages to make it available. It would allow the community to make pull requests to keep it up-to-date, fix
eventual errors, provide examples with other programming languages,...
Or use any other documentation generator with GH Actions/Pages for the same result.
* API versioning *
Currently there is the version number "1.4" on the API documentation page, on the left under the OpenSky Network logo,
but it does not seem to mean anything. I initially assumed that it was the API version, but when the /tracks endpoint
was disabled, the version number did not change. This is quite disturbing when you are used to semantic versioning and
wonder why an endpoint no longer works when the API is not supposed to have changed.
=> Suggestion: Either conform to a semantic versioning schema and provide a changelog when the API changes, or mark
the API as unstable with a big, bold red message in the documentation.
* More secure API authentication *
Currently the API can either be used without authentication, or with basic HTTP authentication.
The problem is that this type of authentication is absolutely not secure. Either we pass the username and password in
clear text in the URL, or we use an "Authorization: Basic <base64-encoded-credentials>" HTTP header in the request. The
latter is a little more secure because at least we take advantage of the security provided by TLS.
=> Suggestion: A simple solution could be to use an API key with the possibility to restrict the use according to the
HTTP referrer (For publicly accessible applications, client-side requests,...) or the IP of origin (Private
applications, server-side requests,...).
Another solution would be to use JWT tokens and a dedicated endpoint to authenticate, but it seems overkill to me.
* More consistent JSON responses *
Currently the format of the data returned by the API may vary. For example, the /states/all endpoint is supposed to
return an array of states (opensky-network.org/apidoc/rest.html#response), but in fact it can return null in
Currently there is the little "LIVE" blinking green dot on the home page, but it only seems to check whether there is a
response when querrying the /stats/facts endpoint. I think this status checker script is a little bit too optimistic
because even when everything is burning and the API returns 502 Bad Gateway errors, it shows this little blinky guy.
Thanks a lot for the constructive suggestions. We are aware that the Live API is another thing that needs to be improved in the medium term. We've started with point #1 now and are evaluating the others!