What makes for a good API?

Liveblog, ODCamp4, , , ,

One of the first questions to come up on day two of Open Data Camp was “what is an API?” One of the last issues to be discussed was “what makes a good API?”

 

Participants were asked for examples of application programming interfaces that they actually liked. The official postcode release site got a thumbs up: “It was really clear how to use it and what I’d get, and I can trust that the data will come back in the same way each time.”

Asked for bad APIs, people said anything that required registration and authentication, and anything that took a lot of time to use. “You’re supposed to be getting real time, dynamic data, but if you have to spend ages getting to it, you’re not getting that.”

So is there any point having an API, or is it better for publishers to just make the raw data available? Participants felt there were use cases for both. Equally: “The crime data is quite interesting. The database is massive, and it takes a long time to download, but the API is incredibly restrictive. So it’s the worst of both worlds; you’ve a dataset that’s very unwieldy but an API that doesn’t make it easier.”

APIs and the diverse demands of demanding data divers

After that, things got technical. What about linked data, versus other forms of organisation. What about file formats, and standards? Perhaps unsurprisingly, different users wanted different things.

One participant suggested API builders needed to recognise that, by making it easier to carry out common queries, while enabling a minority of users to do their own queries. But then, another participant argued that this could lead to vastly over-engineered APIs. “The Nobel Prize committee has released an API for Nobel Prize winners; but they’re just lists, so its massively over-engineered for what is required.”

This theme was of interest to the ONS, which was running the session. A representative pointed out that the postcode example was very specific, while the ONS website had a lot of different datasets. Should there be one or many APIs to access these?

One participant said: “You are the ONS, so we come to you for everything you have.” Having thought about it, though, he noted that if he went to the DEFRA website, it would be for something very specific, such as flood data. “So perhaps I do want an API just for that. I don’t know what I want. Typical bloody user.”

The Key to the API

There was also division on the subject of API keys. Publishers tend to be keen on these, because they generate KPI information. But, with some caveats around what the key might be applied to, users were not keen. “If I am going to do a large volume of work, I don’t mind getting an API key, but for low volumes of work, I don’t want to do that.”

Actually, there was probably common ground around the idea that people shouldn’t have to authenticate themselves for small jobs, but it was ok to be asked for information about who they were and what they were doing if they were going to make big calls on servers or support.

Document it, and then document it again

One thing participants definitely agreed on was that APIs needed to come with good documentation; not least about any restrictions on the use of the data. Preferably written by someone who understands the needs of users rather than “techy people.” Preferably in standard format, such as OpenAPI/Swagger (Terence Eden, tweeted more information about this):

All this needs good follow up, communication, and support – not least at weekends.