vege - Fotolia

Get started Bring yourself up to speed with our introductory content.

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

Join the conversation


Send me notifications when other members comment.

Please create a username to comment.

What is the best approach you've found for developing an open API?
What applies to your code at the unit level should apply to your APIs wrap some good testing around them.  But also look for ways to make them understandable.
@Veretax - I also think that making them understandable is key. APIs, by their very nature, encapsulate and abstract functionality, and expose only an interface for accessing that functionality. I think that API developers often fail to realize just how much of that functionality is not exposed, which can leaves large gaps in the consumer’s understanding of how to best use the API. As I mentioned in another discussion on this article, you have to document your API if you want it to be understandable, and start with using the machine readable format of the API’s definition as the foundation of the contract.
As one who frequently tests a ReST API for my product, the best answer, IMO, is to make sure that the calls to endpoints make sense, and that they do so in clear and unambiguous language.
I think you really have to document your APIs if you want it to be easy to use and understand.  I think that good documentation starts when you go beyond human readable docs and start with using the machine readable format of the API’s definition as the foundation of the contract. The article mentions Swagger, but other good alternatives that can provide this information for consumers are API Blueprint and RAML.