7 steps to achieving a 'perfect' API

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.

Topic: Enterprise Software

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


Log in or register to join the discussion
  • Half of the points...

    seem to be more to do with UI than API?

    Also many times you don't have a choice about JSON over XML. Most of our development requires us to talk to SAP, NAV etc. which means RFC, idoc or XML/SOAP.
  • Building Great APIs: The API Gold Standard

    A few months ago Steven Willmott, CEO of the API Management solution provider 3scale wrote a series of 4 posts on how to build great APIs and what it the "API Gold Standard".

    There are available there:

    Part I: Building Great APIs: The API Gold Standard.
    Part II: Simplicity, Flexibility and Ease of Engagement.
    Part III: The need for API Management and Infrastructure.
    Part IV: Great Developer Support.
    Guillaume @...