vege - Fotolia

Document your APIs and keep them simple

How can developers make an open API easy to use and understand?

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