7 steps to achieving a 'perfect' API

Summary:Simplicity, standardization, security and documentation are gold in the API world.

Is there such a thing as the 'perfect API'? Maybe or maybe not, but James Donelan, who is VP of engineering at MuleSoft, says you can come pretty close. 

Innovation Collage by Joe McKendrick
Photo credit: Joe McKendrick

In a recent post, Donelan provides a series of suggestions on achieving API excellence:

  1. Keep it simple, and RESTful: "Follow a RESTful approach and model your API after HTTP resources and actions – the same way a browser interacts with the web," Donelan advises. "The API should is intuitive and you can tell what it does at a glance."
  2. Leverage the most effective standards: "XML is out and JSON is in," Donelan declares. What's happening with XML? He cites an example from a couple of the big Web properties: "Twitter threw its hands up and now only supports JSON after determining that XML usage was significantly low and JSON was more lightweight and developer friendly. Box ditched XML support after learning that it was horrendous at talking about objects and that less than 0.5% of users still wanted to use it."
  3. Keep things secure: "Use SSL [or Transport Layer Security], without any exceptions," Donelan advises. HTTPS is the best line of defense against hackers. "In addition, when using this approach access tokens can be used instead of requiring users to digitally sign each API request with expensive cryptographic hash functions." Another standard, OAuth, also provides an open mechanism for authentication developers to understand and follow.
  4. Put users in control: "It's a powerful thing," he says. Enable users to sort using various rules, searching and filtering. This also "limits the need for the API creator to have 'different flavors' of the API since it is configurable by the client at runtime."
  5. Provide automatic navigation: "Instead of requiring a user to ‘figure out’ where to go next by manually constructing URLs, have your API ‘tell the user’ where to go to get the next page of data."
  6. Always be backwards-compatible, please: Donelan says this can be accomplished by implementing a "version number into a base URI and also support the latest API version under a versionless base URI." Also, make sure all changes are "vetted and carefully communicated."
  7. Document everything: Always a sore point with standard software solutions, documentation is the key to ensuring that developers down the line will be able to adopt and use APIs.

Topics: Enterprise Software


Joe McKendrick is an author and independent analyst who tracks the impact of information technology on management and markets. Joe is co-author, along with 16 leading industry leaders and thinkers, of the SOA Manifesto, which outlines the values and guiding principles of service orientation. He speaks frequently on cloud, SOA, data, and... Full Bio

zdnet_core.socialButton.googleLabel Contact Disclosure

Kick off your day with ZDNet's daily email newsletter. It's the freshest tech news and opinion, served hot. Get it.

Related Stories

The best of ZDNet, delivered

You have been successfully signed up. To sign up for more newsletters or to manage your account, visit the Newsletter Subscription Center.
Subscription failed.