Three Keys to Good APIs - Part 1 - Transparency

When building integrations for a living, I have formed opinions about which APIs are my favorites, which are tedious, and which are mind-bogglingly incomprehensible. While I try to stay away from making outright recommendations to my customers about whether they should subscribe to a SaaS based solely on the quality of an API, there's no question that it can impact the cost of integration and sometimes greatly enhance (or hinder) what they'd like to do with the SaaS application in their business. So, what do I look for when working with an API for the first time?

When evaluating an API, I look at whether it is:

  • Transparent
  • Comprehensive
  • Extensible


Transparency is a measure of how easy-to-understand the API is. This is a combination of both the quality of the API documentation and the structure of the API. While there is no one "right" way to do API documentation, there are many good examples out there. Here are a few general things I look for:

  • an overview where I can easily find a base URL for the various API endpoints. This sounds like a simple thing to get right, but surprisingly many SaaS apps shamefully omit it. 
  • clear documentation about the type of authentication. This is one of the first things that a developer will need to know about, and this should also be listed and documented clearly and toward the top or overview of the documentation. 
  • general table-of-contents or summary showing all the resources and/or endpoints for the API  (i.e. on one page or on one menu) . I don't know anyone who thinks drilling through five layers of page links to get at resource documentation is fun.
  • centralized documentation of common behaviors across all entities like how to paginate query responses should be consistent and documented in the Overview section.
  • examples! A picture is worth a thousand words and sample request and responses are the "pictures" that developers rely upon to implement and test the parsing of the data. Also, no one likes incomplete examples - show the full detail of a full-bodied request and response. 

Documenting the various API Styles

When judging the transparency I also consider the style of the API ( SOAP vs. REST vs. XML RPC etc..). Ah, dear reader, are you expecting to launch in to a nerd-war tirade on which style is better?  Allow me to disappoint you: 

"I don't really care".

Yes, REST is all the rage these days and there's a lot of bad press about SOAP, but depending on how well-documented the API is, SOAP can still be a fine choice for an API, especially if your services tend to be more complex than resource-driven structures. Conversely, I've seen REST APIs that are shockingly awful because they are undocumented with no endpoint and incomplete resource documentation. Another annoyance is that some vendors claim their API is "RESTful" and then go on to implement only GET and POST methods for all types of resource operations. That's a sure sign that the marketing people had a hand in authoring the documentation. XML and JSON RPC are less-common, but they can actually be quite simple to deploy and use. 


If I'm researching a SOAP API, I want to see the WSDL URL first thing. WSDL defines the endpoints that are exposed, and there are plenty of code generators out there which work with WSDL (I like SOAP UI, but that's hardly the only one). Many times, I've seen vendors simply provide the WSDL URL with a few summarizing comments about their API, and that's it! That's like giving a 10 year-old a key to your car and telling them to drive to the grocery. C'mon!

Good SOAP documentation should still include human-written summaries of each SOAP endpoint. Oh, I know you developers think your endpoint names are self-documenting, but a name is only a name; would an endpoint without explanation smell as sweet? Methinks not.

Another faux pas with SOAP documentation is lack of resource documentation. By resources, I'm talking about the body of the SOAP envelope. Hey vendors, do you provide a bunch of XSD files with no written explanation? I call that, "too lazy to document". XSDs, while not entirely irrelevant, are one more layer of tedium that I'd rather not read through to learn what an API does. What I AM looking for is a nice summary of the XML returned as well as element-level documentation (what's required, what's not, associated business rules). Examples: Autotask has some of the best SOAP documentation I've come across; while Microsoft Dynamics CRM is not organized well around resources or how a developer needs to research the API. Netsuite has a huge API and while it's organization isn't the best, they provide a Schema Browser so you don't have to rely ONLY on XSD files.


I've already alluded to REST's popularity with the marketing department, and when done well, REST does make documenting APIs much easier, because the API will be structured consistently for each resource. You still do need to document your API, though! This is one of the common mistakes I see with vendors that have a RESTful API - "here's an endpoint URL with a CURL call", but nothing else.

REST API documentation should be organized around resources, which means the summary of the documentation should include a list of all resources - duh. Within each resource it's also nice to get a summary of the HTTP verbs that are available on that resource, along with examples of reach API call. A truly RESTful API makes use of the HTTP verbs:

  • GET - to lookup or query resources
  • POST - to create resources or invoke a process
  • PUT - to update an existing resource
  • DELETE - to delete a resource.

This is one of the reasons why REST APIs tend to be more transparent. The verbs (i.e the actions) you can perform on a resource are transparent and well-understood.

From a REST documentation standpoint, Hubspot is my all-time favorite, showing superb organization, and a three-pane view with data examples on the far right as you drill in to each API call.  Constant Contact does an excellent job documenting each resource with lots of examples and best practice documentation. On the flip side of the coin, LinkedIn needs to improve their summary documentation; and they rely on "robo-documentation" from apigee which contains no human comments or other real-world observations; this isn't uncommon - many others, like Trello, have decent organizational structure, but lack detailed comments. Finally, it's disappointing when vendors hide their API documentation behind a signup process (e.g.: UPS). If you're going to though the trouble of exposing an API, why hide the documentation?


So, transparency can be summed up as the ability to easily understand what an API does, including:

  • Well-structured organized summary with one-to-two click access to any part of the API.
  • Explicit example of Authentication style used for API access.
  • API endpoint URLs
  • Human-written action/verb/endpoint documentation
  • Human-written Resource documentation
  • How-To examples throughout

In my next article, I'll write about the second and third keys to making a great API - how comprehensive it is, and whether it is extensible.