Your API Requires What??

If you’ve ever developed for an enterprise IT department, and had to please the end user, you know very well that they don’t care about what your technical limitations are, they care about getting a tool that helps them do their job better. Oh some will commiserate with you about your challenges, and the best of the business side will compromise to get to a product that helps, even if it’s not perfect, but much like everyday consumers, they want what they want, and you either provide it or not. The thing is, in the enterprise, the pool of users is much smaller than for a commercial application, but the users are more focused on what they need, precisely because there are less of them.

On thing that many vendors fail to comprehend is that this “I need what I need and you provide it or you do not” approach applies just as strongly to enterprise developers. While most business to business (B2B) vendors (both hardware and software) understand the need to provide a useful, generally easy to learn user interface or command line, often that understanding does not extend to APIs.

Don’t make API consumers

into this guy.

There is a mentality of “We’re all developers here…”, which is true, but developers have different priorities. Just as the bulk of end users will not use an application that is poorly documented, non-intuitive, and complex, the same is true for the bulk of enterprise developers. They have a goal in mind, are trying to get their job done, and if your API is slowing them down or making their work harder, they will look for alternate ways to achieve their goals.

Oh, for sure there will be a small percentage that dig in and learn the API no matter how confusing and undocumented it is, for a variety of reasons ranging from earning geek cred to project requirements demanding it. But if given a choice, the vast majority of developers will seek an easier way to do what needs doing. They have timelines and deadlines, and will not let something like poor documentation interfere with those requirements.

Yes, stability and predictability of APIs is essential, without those items the toolset will not get used. But without documentation and an intuitive design with predictable types, requests, responses, etc. many developers won’t even get to the stability part. When the tool cannot be figured out in the time available, stability is entirely irrelevant.

So what do you need? Well, I have years of both writing and using APIs, and here are a few tips from me, no doubt others have a lot to add to the conversation:

1. Cohesive design. Most APIs grow over time, but they need to adhere to standards set by the API docs, so that developers don’t waste time going “what is this completely different thing here…?” Variations need to be clearly documented.
2. API reference. A quick reference to help developers understand how to make the API calls, what parameters are, what responses will be, standards supported, and requirements to use the API.
3. A full blown “how to set this up”. Including clear documentation of the things required to use the API. Developers don’t care if you didn’t write part of the toolset – they expect that – but you’d better give them every bit of information they need to configure it for their development environment, including the parts you didn’t write. It’s your API, document all the steps to make it work.
4. Samples. Not “Hello World” level, though that belongs in the API, but real use-case samples that delve in deep, preferably in steps so developers can learn without turning on the firehose.
5. Input/output samples. In the world of SOAP/REST APIs, sometimes you just need to see what the final request going out needs to look like, and what to expect in the response document.
6. High-level APIs. The more mondo-geeky your dev staff, the more likely that they want to expose each little tiny operation your product is capable of as a separate API. But honestly, enterprise developers don’t want to make 50 calls to do one thing common to their industry. It wastes time coding, it wastes network bandwidth, and it makes the application more laggy. To use my utility roots, if “Read a meter” is the command, THAT is what developers want to tell the API. They don’t (and shouldn’t have to) care how many steps that takes, they want the toolset to “just do it”. That is not to say that users do not want access to the individual steps of a process, only that they require one call to achieve one business function. If you don’t have a business layer, go write one. Now.
7. Rockstar support. Seriously, if you want people to use the tool, then you have to give them a way to get solid answers. Places like StackOverflow are great for things a large number of people are using, but for your highly specialized API, not so much. So you have to provide it – in a community, with tech support, whatever way works best, but when stuck, people need their questions answered, not to paw through docs hoping to find some vague reference.
8. Cohesive communications and constant feedback. Getting out there via social media, blogging, meetups, whatever, and talking about changes coming to APIs, new uses some customers have found for the APIs, bugs that are in-line to be fixed and workarounds are pretty darned important. Users want to be informed, and silence about the APIs kind of implies a lack of support going forward – whether that implication is accurate or not, it is perceived. And feedback is where the best ideas for improvements come from. The person who just struggled through implementation of the API for the first time has a unique view on what could be better, and needs a communications mechanism to make those recommendations. Meanwhile, the person whose dedicated a couple of years to production use of the API might well understand the real-world implications of the design better than the original analysts who wrote it up. Again, a feedback mechanism is required.

In the end, the point of an API is to get people to use it. Invest in the API, treat it like a product, even if in your business case it is a feature, not a product. It was developed for a reason, give IT the tools to make that reason real.

And save us all a ton of time trying to figure out how to use it, so we can focus on the overall application, not your tiny bit of it.