7 steps to achieving a 'perfect' API

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.