A few weeks ago, a client of ours asked the question: What makes a good API?

Obviously I have my own opinions on this, but I thought it would be a great opportunity to gather some feedback from the wider Equal Experts development community and beyond. We put together a survey and initially sent it out to the EE community. After a few days we wanted to widen the scope of the data so we blogged about it and sent it out over social media. We got a reasonable amount of responses (over 70) – so hopefully the data is representative of what is currently considered good design practice for APIs.

As promised, here are the results of the survey:

 

The clear preference here is for developers to be able to get started quickly and learn how to use an API by trying it out, rather than first having to read lots of documentation to understand the API in full. This is a common trend towards reducing big design up front (BDUF) – testing libraries out in the open source world, rather than relying on sales brochures or technical specs to describe what a thing ‘should’ do.

Well that’s conclusive – 100% prefer RESTful APIs. The drive to RESTful services is driven by the simplicity to integrate with their APIs – and also the ability to make non-breaking changes to the API, without needing to release new versions of the service. So it’s not really a surprising result, considering the demographic.

With the explosion of Javascript-based frontends backing onto APIs, it’s not surprising that JSON is generally regarded as a crucial representation to be used for APIs – 84.7% of respondents chose 4 or 5 on a scale where 5 is ‘crucial’.

For the same reason that JSON is seen to be crucial, XML is becoming less and less important as a format for communicating between systems.

The importance of HTTP

For the following questions, we can see that consumers of RESTful services really value having the service aligned to the HTTP specification. This supports the principle of least astonishment. Developers of consuming applications will expect services that operate over HTTP to follow the HTTP specification. Otherwise developers need to learn the idiosyncrasies of the service as well as the core functionality of the service. In addition, services that follow HTTP patterns can also leverage built-in HTTP features and internet technologies (such as caching rules).

HATEOAS is a hotly contested design choice. There are benefits to following a HATEOAS style for developers of the API, but it’s an approach that can lead to overly complex implementations on the client side. More investigation is required here, but we can see that opinion is clearly more divided when it comes to this design choice.

Would you prefer to use an SDK or direct HTTP?

There is a clear preference for services to expose a direct HTTP interface rather than providing a client library to integrate with the service. We also asked people to provide explanations for their preference; those in favour of using the HTTP interface directly cite cleaner interoperability, greater freedom of client language choice, less dependencies to manage and freeing themselves up from the providers SDK release lifecycle. Those who expressed a preference for an SDK believe they will get some error handling and boilerplate code for free.

Which API provider have you been most/least impressed with, and why?

Github came out as the clear winner here with nine positive mentions; Slack gets three; Twitter is breaking even on two positive and two negative; Google gets six positive and two negative (across maps, search and cloud platform), while AWS received a couple of positive mentions and a negative one.

That’s it for now…

Many thanks to everyone that responded, and I hope you find this information useful; we certainly found it interesting. We’ve made the full set of data available to download. It could be interesting to run a similar survey at some point in the future to see how things have changed; follow us on Twitter or LinkedIn and you’ll be sure to hear about it.