The presence of an API in the systems we were buying or building used to be a nice feature to have. It would be appreciated by those trying to write management reports, but it would not be foremost in the minds of those making the business decisions.
Today, the API is coming to the foreground. We build our technology solutions out of a mixture of hosted services, vendor systems and inhouse development, and the ability to connect these systems together painlessly is becoming important. Ask the questions below before you sign off.
1. Is the API documentation publically available?
Assuming there is any documentation at all, this is usually a good measure of how mature an API is. If a technologist is ready to publish their interface to the world, this shows confidence that the interface works, and that they are trying to encourage people to use it. If the API documentation is hidden behind partner logins and NDAs, this shows the supplier aniticpates a higher level of handholding and explanation. Which means more work on your part.
2. Does the API documentation cover messages/methods, fields and values?
API documentation should minimally tell you what messages you can send / methods you can call. Better if each field is described. Best if the allowed values and constraints in each field are enumerated. There is a special circle of hell reserved for people who write things like “systemGUID: use this field to specify the system GUID.”
3. Does the API documentation cover error cases / codes?
Often neglected in API documentation are the error cases and error codes. I’ve never seen this done perfectly, but a list of numeric codes with explanations of likely causes and remedies is always welcome.
4. Is there an SDK?
The presence of an SDK is another sign of maturity, along with public documentation. A lot depends on the quality here, and you’ll probably have to load it up and spend a few hours using it to find out. Any SDK purporting to be .NET should work in the latest version of Visual Studio without making you jump through project upgrade hoops. Can you make a basic call to the remote API? Is there a test account present for specifically this evaluation purpose? What you are looking for is saving time, and if you’re left feeling “maybe it would be easier to go straight to the database / web services, everyone’s time is being wasted here.
5. Are there end-to-end working code samples?
Although there are a few stateless APIs, most follow the pattern below:
a. Make an authentication request
b. Receive some kind of secret key
c. Make your business requests using the key
d. Sign off
The business request itself may be broken into more than one stage – for instance, if you are updating a contact in a CRM system, you may first need to search for and retrieve an API reference for the contact before being able to udpate it.
So all of this adds up to you having to make a *sequence* of linked calls, which in turn means having some full examples showing you how to do this. But even though it sounds important, most API documentation won’t show them. If you’re lucky, there’s an out-of-date SDK, but chances are you’ll have to phone the company in question.
6. What technology choices does the API support?
This is just a straight question, and depends on your requirements. A SOAP or REST interface is the standard, and will give you plenty of modern choices. Although Amazon Web Services is an interesting example of an API that is ostensibly open (REST), but complex to use, so you are effectively tied to whatever platform you can get an SDK for. (I only know this because I investigated what would be involved in creating an MD5-signed request to AWS in VBA – mon dieu!)
7. Does the API give you a receipt?
Any API should give you some kind of reference to any objects you create or update, and don’t under any circumstances touch one that doesn’t. Better still, you ought to be able to pass in your own reference. The receipt or reference becomes crucial as soon as you want to ’round trip’ an API call. If you don’t get one, you are left with a nasty correlation problem, and end up trying to guess which output record from the API corresponds to your input record.
Whether it’s your own reference, or a system-generated one, make sure you also understand how long those references are good for, and also that you’ve sufficient capacity for your own purposes. (In a trade flow where you might be passing millions of records a day, a ten or thirteen character field is not going to give you much room for comfort.)
8. How is the API metered/throttled?
Per-request is the most common, but you’ll also see bandwidth and storage with modern cloud services. Be very wary of any APIs that are metered per-user, or by the number of simulataneous connections. It’s not that there’s anything *theoretically* wrong with these things, it’s just that if either you or the API-provider don’t clean up old connections properly, you’ll get locked out, which is annoying and hard to debug. I’ve encountered this on two different APIs, and it just makes you want to kill the vendor.
9. Does the API allow reference data updates?
As the systems you target get bigger and bigger, reference data becomes more and more of a challenge, especially when you are integrating System A to System B, rather than User A to System B. You can make User A re-enter information they’ve already entered elsewhere or manually correlate new records to identifiers in System B (as anyone who’s tried to open a new savings account with their bank can attest), but System A and System B are going to need a more resilient method. For a given entity, System A must know System B’s identifier, or how System B correlates to that entity, otherwise you are going to lose referential integrity. In the ideal world, reference entities are managed in one place, and this ‘golden source’ propagates changes to downstream systems throughout the enterprise. If you ever meet anyone who thinks this sounds easy, ask them if they have a global canonical source of country names*.
10. Does the API support asynchronous calls, and if so, how?
For long running transactions, we may well need to tell an API to do something, and then come back some time later to check the results. One way of accomplishing this is with a ‘polling’ architecture. So we make our request, and we are then responsible for monitoring a message queue or a database table for notification of the result. The alternative architecture is to pass in a custom callback on the request side, so that the API itself can call a function when processing is complete. A well known example of this is PayPal, where you pass them a URL they can ‘ping’ when a payment is completed.
In summary, these are all good questions to ask when evaluating an API. Since the exercise of selecting an API usually happens as part of a wider technology decision, you might not get much time to ask them, or to do much about the answers. Inside that context, I’d focus just on the correlation question. It is a fundamental requirement, and coding around a poor or lazy solution is painful and frustrating.
*Don’t ask this in America. A list of US states and ‘Rest of World’ is not the right answer.