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."
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.
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.
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).
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.