To keep up with the changes and new trends appearing in the world of technology, developers have to speed their learning and acquire new skills at a blistering pace. One of the things they need to know how to build and work with are Application Programming Interfaces (APIs).
APIs have become crucial for business success and should not only work well but also look good and be understandable. They are more than just machine-readable interfaces to some data and services. The way an API will interact with users makes, in fact, a significant part of the success mentioned above.
The first to deal with your API will most likely be a developer. Apparently, they would prefer it to be easy to understand and be aligned with their technologies. That is why it is important to give careful consideration to some of the aspects that would substantially determine the go of your API.
The Technology/Format/Type Issues
The REST/JSON vs. SOAP/XML choice is not that difficult to make if your target customers -- not to mention the use cases -- are taken into account. If they are script-oriented developers, REST/JSON is the choice. If high expectations on quality of service (QoS) are involved, SOAP and its standards are what is needed.
Want to make developers’ life even easier? Add some hypermedia and save them hours of groping the documentation you are yet to create. If you are not sure what media format to choose, here are some of the most commonly used ones talked about.
Vocabulary United
Paying attention to the naming used in the data exposed by your API may ease its adoption by the end-user greatly. Ideally, it should be similar to that of other services or those that can be integrated with yours.
Authorization and Security
If on the step of choosing types and formats you opted for REST/JSON, OAuth will perfectly suit here. Not sure which version to choose? Find them described here. If SOAP was your option, you could choose SAML or WS-Security.
You are to decide if transport level security (TSL) is enough. If not, the data exposed with your API should be signed / encrypted / both signed & encrypted.
Versioning
When planning on how to version your API, you should decide if you will, for example, include versioning in the URL, or return it in the content-type. For HTTP/REST, your strategy may be based on paths, query arguments, or HTTP headers. For SOAP, it may be based on namespaces or endpoints.
Documentation
Documentation teaches how to use your API, and that is why you should consider making it as detailed, unambiguous, and rich in code samples as possible. You could use documentation generators. Some of the most trustworthy ones can be found here.
The points mentioned above are merely the basic elements of API design. We recommend Undisturbed REST: A Guide to Designing the Perfect API by Mike Stowe to dive deeper into the topic.
