API Hospitality: Welcoming Developers with Documentation

What is API Hospitality?

Hospitality is the art of making guests feel welcome. As humans, we are taught how to welcome people, smiling, saying we’re glad to see them. As developers, we try to do the same thing by offering friendly user interfaces and documentation for our users. However, there’s a category of users who often get ignored — the people who interact with our product through APIs. I think this is because we assume that since they are also developers like us, they will understand the same things we do.

This assumption is often wrong. So how do you work API Hospitality into the forefront of your process? And how does this relate to your documentation?

Common Traits Among Companies Famous for APIs

Companies become famous for APIs when they solve for important or common problems and are easy to understand and use. Many people have opinions on the specifics, here are some that stand out to me.

• Easy to play with — Sandboxes with realistic (NOT REAL) data are the best kind of advertising. You let people see what they can have if they jump through your hoops. Stripe and Twilio are both good examples of this step.
• Easy to integrate — I once spent two weeks trying to get an early version of Swagger to work with my data. I couldn’t figure out what I was doing wrong! It took someone else to point out that I needed to be hosting a webserver. Now that they’ve addressed this in OpenAPI with easy hosting, it’s a lot easier to encourage people to try it out without setting up Apache.
• Minimizes pain points — Is there a thing such as beautiful data architecture? We are all just accreting things behind the curtain. But when people come over, they don’t need to see the dirty dishes if your data design has rationalized endpoints.
• Elegant = Beautiful x Useful

Which often comes down to the welcoming manner they invite in, and communicate with, their users. This often starts with (but rarely ends with) their documentation.

Why Do People Use API Documentation?

Everyone reading API documentation is already interested in your product. They’re looking for a way to make it work with what they’re building. API documentation is a way to describe the surface of your application and data in a consistent way. When people build with Legos, they have a specific terminology that describes the number and depth of the studs so other people can reliably duplicate the build.

This means it’s relatively easy to understand what they are looking to do and understand, unlike end-users, who may have a bunch of different goals or priorities. API users want to:

• Connect with the appropriate level of security.
• Get or put data consistently.
• Get confirmation that their requests have been completed.
• Pass through states accurately.

For example, Kin Lane posted recently about an interesting way to use publically-facing Google Sheets and JSON to access the information in sheets programmatically. I think that’s super interesting, and would solve a problem I have where I have survey data in sheets but can only generate static reports. I find myself wishing that someone would give me an example of how that would work so I could understand it better.

But Kin is a blogger and isn’t in the business of writing formal documentation. Google hasn’t documented this at this point in time because it’s not an intentional interface. One could argue that’s how a lot of APIs start out — a one-off for a customer, a side effect. So, what if Google made this aspect of Google Sheets easy to use, documented it, made the URLs prettier — would more people use it? Probably. And what if they created tools that would make it even easier for the next generation of users?

Each of these hypothetical steps would make using the data easier, and more hospitable.

Why Do API Docs Fail?

If it’s so simple, why do people find so many API documents hard to use or lacking in essential information?

• Authentication is hard — even though we have standards, security is hard, and the problem, is, as always, usability.
• Data design wasn’t built with the user’s side in mind.
• The endpoints are not written in a uniform way.
• Stuff was left out.
• The documentation was auto-generated and not cared for.
• Index/search lack analytics.

In other words, the value of the API is either badly conceived of or badly articulated to potential users. Or both.

What is the Real Value of an API?

When we invite people over for a party at our house, we get the joy of conversations and connections that wouldn’t have been possible alone. The same is true of hospitable APIs — we are offering a chance for people to make things that we don’t have the time, ability, or business reason to create. We benefit from the enriched ecosystem for our product, and our partners benefit from our work and access to our “good stuff”.

That’s why APIs in general are important. But why is YOUR API, in particular, important? What is the value you’re offering? Why is your application or data set so important? You need to understand these answers before you can reasonably serve your users.

In order to have good documentation, you need to have a good understanding of the value of your API or else you’ll be communicating the wrong problem. Some things to take into account when trying to understand this:

• Modularity — It’s easy to make things consistent and repeatable if you’re building them on a known structure.
• Efficiency — Why repeat work someone else has done? Also, many applications can use several different types of data with the same level of work.
• Ease of Use — It’s relatively easy to find someone who understands the theories of REST and SOAP, much easier than teaching someone your own unique data architecture.

People are using your API because you’re saving them from reinventing the wheel, not because your API has inherent worth. The worth is contextual, and it decreases the harder it is to use the API. Have you been fine-turning your API with an eye towards this?

• Testing — Make sure the calls actually work for more than internal users. This is a shockingly easy thing to miss, and quite painful for integrators
• Troubleshooting — Give people USEFUL error messages when something goes wrong, and things they could try to fix it.
• Mapping Paths — Work through how you are using the APIs, and then create and document a couple additional paths based on beta users or previous API uses. Working from the outside point of view will help you find the things you’re overlooking from the inside.

How Do We Make APIs More Hospitable?

So how can we use this to create a roadmap for building hospitable APIs? What are the elements of a welcoming and usable API?

• Docs — Make documentation a priority. Consider hiring someone to write them, or at least set up the architecture of the documents so it works well with the automatically generated docs from your API spec. Spend some time introducing the idea of your API and how it could be used.
• Consistency — When you’re constructing your API, make it internally consistent. Don’t change up the way you do capitals or anything about the naming schema. Pick a style, document it, and stick to it. Consistency is like having clear floors for a party. No one wants to trip over a surprise ottoman in the middle of what they expected to be a walkway.
• Examples — Humans learn better from concrete examples than from abstract descriptions. You can read as much as you want about how to remove a wine cork from the bottle, but it will make more sense to watch someone else do it — and the most sense to actually do it yourself. There is something about the way the bottle fits in your hand and the wiggle required to extract the cork that is difficult to convey in mere text. Every good example gives API users the opportunity to fit your tool to their hand and their purpose.
• Clear Communication — One of the things you know about software is that it changes. Once people have built applications on top of your API, though, they are counting on it remaining relatively stable. Therefore, you need to commit to telling them when something changes, preferably before it changes. Think of this like the updates to a party invitation. If the original invitation specified cocktail dress, and the venue changed and now you’re throwing a casual picnic at a park, people need to know both the new dress code and location. You can’t wait until they show up to tell them about the new thing. Causing awkwardness or breakage is the opposite of hospitality.
• Versioning — Versioning indicates that a change has been made, but you need to be sending out messages long before a change is made to warn users. If you’re doing some kind of authentication, you probably have some contact information for your API users which you can use that. Remember that the people using the current API may not be the people who wrote it or put their contact info in. You may need to figure out how to communicate with an entirely new set of people.

Summary

The difference between adequate and welcoming APIs is like the difference between walking into an empty conference center and one full of signs and people telling you you’re in the right place. The experience and the communication is what matters, not just the bare location. Understand the invitation you’re issuing, and make it easy for people to accept.

Documentation tools are awesome, but they are secondary to thoughtful consideration of your users and their needs. Once you start thinking about making the API experience hospitable, and committing resources to do so, you will be better serving the user. Consider your value proposition and how both to the integration developers and the people who pay the bills can be charmed, by hospitable, usable, warm, and open APIs.

DISCLOSURE STATEMENT: These opinions are those of the author. Unless noted otherwise in this post, Capital One is not affiliated with, nor is it endorsed by, any of the companies mentioned. All trademarks and other intellectual property used or displayed are the ownership of their respective owners. This article is © 2018 Capital One.