One of the big launches in the Finnish API scene this autumn has been Finavia API. It offers an API for requesting Departures, Arrivals and Queue sizes from airports in Finland, managed by Finavia.
As an API enthusiast this was something I just had to get my hands on and I'm happy to share my findings for everyone's benefit.
We do a lot of API consulting and training in Osaango, but one of our key services is also API Design reviews, which test the API for both technical implementation, usability and marketability from developers perspective. We also develop and support the open creative commons method for creating good business oriented APIs in a lean way:
Finavia API & Developer portal - almost there, but some room for improvement
In general, I managed to use the API, it's quite simple. It has some of the
But there were some hick-ups in the process before I even managed to make my first API request.
I'm walking you through some of the findings. Of course this is not our normal full review and even if your API has all these issues fixed, there are usually plenty of others to be found. But fixing these is already a good start.
Some of the issues are also standard 3 Scale API management platform issues, Finavia uses quite standard setup. 3 Scale was bought some time ago by Red Hat, which just recently was acquired by IBM.
Signing in and finding my way
Creating a user account in the platform was quite easy. The picture above is the first screen I got after signing in.
The style of text under "Your Applications" is hip and cool, but maybe the tone of voice and the content could have been adapted more to suit the flight scene. Also I had an urge to click on the icons, specifically the "Add application" to actually get where I can add it. But no, those are not buttons or links.
Then where should I go to create the application?
Of course, I need to click the light blue "Details" in the bottom corner. How intuitive. Specially when there are 2 APIs to choose from, the Public Flights (v0, what's that about !?!) and the Queues. Both have "Details" button.
So of I go, to the details.... The adventure begins!
Creating application - or trying to....
Many API management platforms require the user to create an application, i.e. give a little information on a particular use case or client application and in return get an application specific app-id or client-id what to use for authenticating API requests. Sometimes together with an API key, sometimes with some other authentication methods.
I tried to create an application without description, as the field wasn't marked as required field.
There was an error message and then the SERVICE information changed to ",",
This caused the creation of new application to fail.
And then I get to see a standard 3Scale error page. Which is a bit confusing, since as a normal API developer, I may not have any idea what is 3Scale and what does it have to do with Finavia API. Also there is no way back to previous page.
At the end, I did managed to create the application successfully and get my API keys. It was a bit confusing, I was in the application page and suddenly the API documentation was in a sub tab, called Documentation. But found it.
Onward, dear API developers, the goal is near!
Get me some flights... flights... all... all... is there an echo?
Now that I had my API keys, I could concentrate on the actual Flights API.
After about 5 seconds of going through the documentation and it left me with some endpoint design questions?
Why use short versions (dep and arr) for flight types, and why is it called a "type" at all?
Why not just do different endpoints for arrivals or departures. First thought seeing the "flight_type" for me is to choose from domestic or international, not arrivals and departures. And why save space here?
Also, let's look at what the base URL and the enpoint URL is when combined with parameters.
Can't help the feeling that someone has invented a REST echo here... You know "/flights... /flights... /all... /all...
It's an interesting but not necessarily wrong decision to put all filters (airport, departures or arrivals) as URI parameters, as in this case you could even argue they are identifying different resources. But this is a road which should not be continued further.
Final thought on the endpoint design is that based on documentation I have no idea what the results will give me.
After making the first successful request I'm suspecting I'm getting arrivals 24 h in the past and I don't really know how many hours in to the future. Maybe filters here? or at least documentation? Also searching with flight number or destination might be nice, that's usually what i do with the user interface version of Finavia's service.
Data freshness and polling madness
If data is updated only 1 per minute and there is a minimum poll interval of 30 s, why are there no hooks? I mean web hooks or REST-hooks available?
Unauthorized or Forbidden - that is the question
Even after I got API keys, there was still a red exclamation icon visible in the documentation saying I need API keys.
If I ventured in the bottom of the page, I found Try me -button, which actually let me execute the request without giving the keys separately.
Without the API keys, the Try me -request results in 403 Forbidden and error message "Authentication parameters missing". The proper HTTP status code in this case is 401.
Unauthorized. 403 Forbidden should be reserved for authorized requests for which the user just hasn't got authorization.
In this particular API with public data, having only API keys is ok specially in the header. Much better than nothing at all or having them as query parameters. Just don't use that for more sensitive data, and even in public APIs it's not necessarily the best solution.
The State of Status codes
The only documented status code for successful response is 200. When testing the API, I tried find flights with a non-existing aiport, XXX. I got an empty Flights node. In this case I would have expected empty result and 204 status code.
<?xml version="1.0" encoding="UTF-8"?>
As all of the parameters are URI parameters, the only options in this case for other HTTP status codes than 200 are 404, 401 (not 403) for Unauthorized) and I probably would get a 500 if the server failed.
On a general note, the response headers coming from the server are quite nice and clean. Maybe a bit too much info in the response headers about the server and authentication solution for my taste, related to security issues.
On a Date with Data types
I just have one question: why XML and why as the only choice?
Plus points for using ISO dates in UTC with time zones!
But huge minus for offering no documentation on the attributes for the responses?
Directly publishing your internal data structure names is not usually recommended. I'm just asking what is mfltnr or ablk-d ?
English for non-aviators please?
Ok, this was just an example of one API. I hope this helps you. Why were these small things so important?
Some things are cheap to do when designing and costly to fix when already launched and will continue to be costly through added support work, less adoption and bigger transitioning costs to new versions
P.s. After I published this blog post Finavia's Tommi Vihervaara commented they have already started to develop Flights API v2.0 due to launch in 2019. According to Tommi, many of the things mentioned in the blog will be fixed in the new version and even some not mentioned here. Some fixes are related to the 3Scale platform, hopefully fixed in next versions.
If you need a review on your own API we typically go through up to 20 things in our list to review your API and documentation.