- Posts: 9
- Thank you received: 4
- Home>
- Forum>
- OpenSky>
- Feature Requests>
- API - Suggestions for improvement
API - Suggestions for improvement
3 years 3 months ago #1578
by jbroutier
API - Suggestions for improvement was created by jbroutier
Hello,
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
some cases:
- Non-tracked aircraft: opensky-network.org/api/states/all?icao24=ffffff
- Bounding-box without any aircraft: opensky-network.org/api/states/all?lamin...ax=1&lomin=1&lomax=1
A perfect pitfall awaiting for you.
=> Suggestion: Stick to a single type for collections. Nullable fields are fine for scalars.
===========================================
* More consistent HTTP response codes *
Currently some HTTP status codes are misused. For example:
The /states/own endpoint is supposed to return an HTTP 403 Forbidden response if you are not authenticated. It should
be an HTTP 401 Unauthorized response (See developer.mozilla.org/en-US/docs/Web/HTTP/Status/401).
Also, some error messages are returned as plain text, others as HTML, and others as JSON. For example:
opensky-network.org/api/flights/all?begi...67199&end=1628502117
It returns JSON: ["Start after end time or more than two hours of data requested"]
opensky-network.org/api/flights/arrival
It returns HTML: <html><body><h1>Whitelabel Error Page</h1> ...
opensky-network.org/api/states/all?time=-1
It returns plain text: Historical data more than 1 hour ago can only be retrieved with /states/own
=> Suggestion: Stick to JSON since the API is supposed to return JSON data. Maybe use something like that:
{
status: 400,
message: "Missing parameter 'something'."
}
And use the adequate HTTP status code.
===========================================
* Provide an API status page *
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.
=> Suggestion: Maybe use something like Atlasian status page ? (www.atlassian.com/software/statuspage) Or a
self-hosted page with something like that ? (www.npmjs.com/package/website-pinger)
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
some cases:
- Non-tracked aircraft: opensky-network.org/api/states/all?icao24=ffffff
- Bounding-box without any aircraft: opensky-network.org/api/states/all?lamin...ax=1&lomin=1&lomax=1
A perfect pitfall awaiting for you.
=> Suggestion: Stick to a single type for collections. Nullable fields are fine for scalars.
===========================================
* More consistent HTTP response codes *
Currently some HTTP status codes are misused. For example:
The /states/own endpoint is supposed to return an HTTP 403 Forbidden response if you are not authenticated. It should
be an HTTP 401 Unauthorized response (See developer.mozilla.org/en-US/docs/Web/HTTP/Status/401).
Also, some error messages are returned as plain text, others as HTML, and others as JSON. For example:
opensky-network.org/api/flights/all?begi...67199&end=1628502117
It returns JSON: ["Start after end time or more than two hours of data requested"]
opensky-network.org/api/flights/arrival
It returns HTML: <html><body><h1>Whitelabel Error Page</h1> ...
opensky-network.org/api/states/all?time=-1
It returns plain text: Historical data more than 1 hour ago can only be retrieved with /states/own
=> Suggestion: Stick to JSON since the API is supposed to return JSON data. Maybe use something like that:
{
status: 400,
message: "Missing parameter 'something'."
}
And use the adequate HTTP status code.
===========================================
* Provide an API status page *
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.
=> Suggestion: Maybe use something like Atlasian status page ? (www.atlassian.com/software/statuspage) Or a
self-hosted page with something like that ? (www.npmjs.com/package/website-pinger)
- strohmeier
- Away
- Administrator
-
Less
More
- Posts: 393
- Thank you received: 93
3 years 3 months ago #1593
by strohmeier
Replied by strohmeier on topic API - Suggestions for improvement
Hi,
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!
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!
The following user(s) said Thank You: jbroutier
- strohmeier
- Away
- Administrator
-
Less
More
- Posts: 393
- Thank you received: 93
3 years 1 month ago #1662
by strohmeier
Replied by strohmeier on topic API - Suggestions for improvement
I think the pain point #1, the performance, has been much improved right now. Let us know how it works and also any further suggestions (new or old).
