What are the most important features of a great API?

sneakyimp

We've probably all worked with APIs before. E.g., Paypal, Google Maps, Amazon Web Services, Twitter, Facebook. I am facing a project where I will likely be constructing an API and, while I have definite ideas about what it must do, I was hoping folks might chime in with any anecdotes or opinions about what exactly goes into an API to make it great.

I'm thinking it needs several features:
Easy, Secure Authentication - must we pass our ID and KEY with every request? Or does it use tokens?
Clear Documentation - PHPDoc is nice, but clear, well-organized functional descriptions with examples are critical.
Code Libraries - I've seen a lot of poor code libraries written in PHP (AuthorizeNet cough cough cough). Is it really worth it to offer code libraries to your users or is it better just to offer a RESTful interface? SOAP anyone?
Flexible Interfaces - We can deliver XML responses? JSON? CSV? Other?

Let me know what you guys think..

laserlight

I note that "API" refers to the interface and related tools provided by some kind of library/framework, or in the sense you're thinking of, external software (or more specifically, web services).

That said, if we only consider APIs for web services, I agree with your points except for "flexible interfaces", by which you actually mean flexible data exchange/transport formats: I don't think that it is important to provide multiple formats. It can be a nice thing to have, but from the Zen of Python: "There should be one-- and preferably only one --obvious way to do it."

For "code libraries", I suggest providing a pseudo-RESTful interface. I prefix with pseudo because few people follow REST properly, and in the end it might not actually matter anyway. From this interface, you (or interested third parties) can always write wrappers in target languages.

For authentication and authorisation, I think oauth2 bearer token over TLS is a good compromise: it doesn't seem so complicated as other schemes in use, yet it isn't so problematic as having to pass fixed credentials with every request (not that the token isn't fixed, but it is more easily renewed).

Bonesnap

I use Authorize.Net quite a bit at work. It was definitely an uphill battle for the first little while (I have some issues with their code libraries), but now that I've trudged through the mud enough I can use it with relative ease, but it seems I am always discovering something new or a "better way" to do things with it.

NogDog

sneakyimp;11044177 wrote:
...SOAP anyone?...

No! (I've already spent way too much time this year dealing with wsdl, xsd, and other 4-letter words like SOAP.)

sneakyimp

laserlight;11044193 wrote:
I agree with your points except for "flexible interfaces", by which you actually mean flexible data exchange/transport formats: I don't think that it is important to provide multiple formats. It can be a nice thing to have, but from the Zen of Python: "There should be one-- and preferably only one --obvious way to do it."

Philosophically, I tend to agree, but some folks prefer XML and some other folks (like me) prefer JSON or something which is much much much easier to just unserialize and start parsing. I mentioned this because one of my projects involves a bunch of XML zealots. I just don't get it.

laserlight;11044193 wrote:
For "code libraries", I suggest providing a pseudo-RESTful interface. I prefix with pseudo because few people follow REST properly, and in the end it might not actually matter anyway. From this interface, you (or interested third parties) can always write wrappers in target languages.

In what sense do you mean PSEUDO? Could you identify whatever critical component that most people are failing to provide?

laserlight;11044193 wrote:
For authentication and authorisation, I think oauth2 bearer token over TLS is a good compromise: it doesn't seem so complicated as other schemes in use, yet it isn't so problematic as having to pass fixed credentials with every request (not that the token isn't fixed, but it is more easily renewed).

Unless I'm mistaken, requiring authentication with every request reduces the need of the server to maintain sessions or state. It's easy enough to check each request to make sure it's authorized and you don't have to maintain a session table. I suppose the disadvantage of this is that one's credentials are constantly flying back and forth across the internet with each request. From a code perspective, it probably has no impact because you would just store the credentials in a config file somewhere and design your code library to provide them as needed. From a client perspective, authentication-every-time seems simpler to me because you don't need to worry about session timeouts or an extra call to authenticate before performing some operation or storing a token in your code.

Weedpacket

sneakyimp wrote:
Could you identify whatever critical component that most people are failing to provide?

I'm going to guess exploiting HTTP's PUT and DELETE request methods.

laserlight

Weedpacket wrote:
I'm going to guess exploiting HTTP's PUT and DELETE request methods.

Yeah, I had HTTP methods other than GET and POST in mind, but more than those, I was thinking of discoverable APIs instead of the usual out-of-band documentation.

sneakyimp wrote:
In what sense do you mean PSEUDO? Could you identify whatever critical component that most people are failing to provide?

Here's an article that identifies quite a few of them: How RESTful is Your API? The observations were true in 2012 and remain true today. The thing is, they are critical in the sense of definition of RESTful, but not critical in the sense that an API can do without them and still work well.

sneakyimp wrote:
Unless I'm mistaken, requiring authentication with every request reduces the need of the server to maintain sessions or state. It's easy enough to check each request to make sure it's authorized and you don't have to maintain a session table.

Yes, if you want to have a token (however it is passed around), it means you need to store them, whereas you need to store the credentials either way and can possibly just use HTTP basic authentication over TLS. On the other hand...

sneakyimp wrote:
I suppose the disadvantage of this is that one's credentials are constantly flying back and forth across the internet with each request.

Yeah, I don't like this aspect, even though it is all encrypted, especially since these are more likely to be very long lived compared to tokens, and might even be the credentials of a user account that is not purely an "API user". Of course, you could provide a randomly generated API key, but that's a (long lived) token by another name.

sneakyimp

OK yes I think I'll be making a REST-like web service rather than a genuine RESTful web service. There are a couple of things I'd like to do:
send appropriate error codes when a request is bad
make the web service discoverable to some extent.

I'm still digesting the 'how restful is your api' article, but some of the non-restful qualities of popular APIs seem pretty pragmatic to me.