If you publish an open API that is difficult to integrate or that adheres to no standard or an inappropriate standard,...
no developers will use the system. The best way to make sure your API will be used is to try it in your own applications, commonly known as "eating your own dog food."
It's important to determine which API standards to use, because each one is targeted at a specific audience. If you want to support the largest number of users, use a very simple API that doesn't require a lot of overhead, such as a RESTful API. REST standards are rather lenient. The best approach is to be consistent across your API. For example, I don't use SOAP because it's overly complicated.
SOAP was a leading protocol for building Web-based APIs, but it's antiquated when compared to REST and JSON. I find that returning JSON in responses instead of SOAP and XML can make life easier. JSON lets me return a simple object format that's easily parsed in almost any programming language.
API learning resources
I've only touched on the evolving standards and practices in API development and design. Here are new and oldie-but-goodie sources for more information:
Choosing between REST and SOAP
SOAP vs. REST: The war between simplicity and standards
Why JSON triumphed over SOAP
NetBeans creator gives tips on API design
REST or SOAP: Which is best for mobile development?
Adhering to common API standards for authentication (e.g., OpenID, OAuth, and SAML) can make your APIs easier for developers and non-developer customers to use. If you're not dealing with authentication for users, however, use the simpler HTTP-based or token-based authentication, instead of OpenID, OAuth or SAML, which are designed primarily for authenticating as a user.
In addition, providing an open API that documents itself is beneficial for developers. I recently started adding Swagger API documentation to my APIs. Swagger allows developers to generate code automatically for APIs that works in multiple languages. If you don't follow this approach, you will need to at least make sure you offer API client libraries in the most popular languages, such as Java, Node.js, Python, Ruby and Objective-C (for mobile applications).
The key is to follow the software creed of simplicity and standards. Don't reinvent an API, and don't over-complicate things like authentication.
TechTarget Executive Editor Jan Stafford provided additional reporting for this article.
Dig Deeper on API management strategy
Related Q&A from Chris Moyer
Event-driven computing means no IaaS provisioning and no data center to run. Can I migrate all enterprise apps to be event-driven? Continue Reading
What is runtime as a service and how does it differ from platform as a service and infrastructure as a service? Continue Reading
The DevOps model is taking off as cloud adoption grows. But what exactly are the key responsibilities of a DevOps team in the enterprise? Continue Reading
Have a question for an expert?
Please add a title for your question
Get answers from a TechTarget expert on whatever's puzzling you.