7 important considerations for building a dynamic API

Developers don’t have it easy these days. The shift to mobile is forcing them to learn a slew of new languages and tools, the shift to NoSQL requires them to give up their beloved SQL subqueries, and the cloud is encouraging them to build for distributed scalability from day one. Top that off with the realization that great APIs are crucial for your business’s success in this distributed and interconnected world, which requires that APIs not only work well, but look good too.

“Wait a second,” the avid developer interjects, “APIs don’t ‘look‘ like anything. They are just a machine-readable interface to your business data and services. I can dress them any way I want.”

Think again…

Actually, the “user interface” of an API is crucial for its success, as many other API evangelists will tell you. I’m not talking about a graphic front-end for testing the API, I’m talking about the API itself and how it interacts with its users. The first to interact with your API will most likely be a developer at your customers’ site, and developers are generally impatient and want APIs to be easy to understand, follow conventions, and be aligned with the technologies of their domain (oh, and to actually work).

So, before crafting your industry-disrupting API – you need to give careful consideration to the following aspects:

Choice of technology

REST or SOAP? XML or JSON? The list of acronyms is constantly evolving. You need to go to your primary target customer to make the right decision; are they script-orient mashup developers? REST/JSON is probably a good choice. Are they transaction-aware enterprise customers with high expectations on QoS? Perhaps SOAP with all WS-standards would be their preferred solution. Or are you streaming video content in real time? Then a streaming/binary solution will probably work best – for both you and your user.

Naming and Vocabulary

Once you’ve decided on technology and message format(s), put some effort into the naming used in the data exposed by your APIs. Is it in line with industry standards (if there are any)? Is it similar to other services that expose similar data or that might be integrated with yours? You could even ask if it will work with common code-generation tools that your customers might be using – all to ease adoption by the end user.

Authorization

The list of authorization-related standards is also a bit confusing and, to make things more complicated, many key players have chosen their own interpretation of them. For example, OAuth 1.0 has been implemented in different “flavors” by different parties. Which should you adhere to? Once again, your end users and how they will consume your APIs will give you direction. OAuth makes perfect sense for the REST/JSON crowd – but which version? (1.0, 1.0A, 2.0?). For SOAP/WSDL there are several standards to choose from (SAML, WS-Security, etc.). Make sure you choose one your end user is accustomed to.

Security

Is transport-level security (i.e. https/ssl) enough for the data exposed with your API? Or should the exposed data be encrypted (so no one can read it), signed (so you can be sure it hasn’t been changed), or both? Should the security policy be maintained even when the data leaves the wire, for example, in log-files, databases, and further transactions? If the latter and you have opted for an HTTP-based REST solution, standards are scarce – maybe SOAP would be a better choice (with its abundance of security-related constructs).

Versioning

As your APIs evolve and you add new features, you will most likely be required to provide access to older versions of them for your initial customers. Make sure you have a versioning strategy in place from day one. For HTTP/REST, it might be based on paths, query arguments or HTTP Headers. For SOAP, it might be based on namespaces or endpoints.

Automated Key Generation

If your API requires an access key, this has to be a no-brainer to get started with. Developers are impatient folks. Make sure you don’t lose their attention by making them wait a day or two for their keys. They will be looking at your competitor in the meanwhile.

Documentation

You could argue that the documentation is a separate artifact and not part of the API itself – and it’s definitely not invisible (which would pose problems beyond the scope of this article). Nevertheless, I’m sure you’ll agree that it is crucial for your users to get up and running with your API; make sure your API’s intent is clear and unambiguous. Be straight to the point and generous with code examples (in the languages your users are using).

Ori Pekelman gave an amusing presentation at the apidays.io conference in Paris earlier this month in which he launched his 3:30:3 Litmus test for APIS: “

On the homepage of your API, a developer should:

• Understand in 3 seconds what your API is for.
• Be able to identify the entry point in 30 seconds.
• Be able to create an account, call the system, and use the result in under 3 minutes.”

Now that’s what I’d call usability.

So how do you go about making all these choices to ensure your API success? The answer has been hinted about, and I’m sure you have it already – listen (and talk) and adapt to your customers and end users. Create personas for them; let them help you make the right decision (more on that in future blog-post).

And promise me one thing: that you’ll think wisely before implementing your API strategy, because developers don’t have it easy these days.