vege - Fotolia
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
Related Q&A from Chris Moyer
Can an application have Python as a container, run SQL queries on an external Microsoft SQL database and publish the results on an Apache web server ... Continue Reading
The wait is over, as you can now trigger Lambda functions with SQS messages. Follow these steps to get up and running with this new capability. Continue Reading
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