mark nottingham

User Personas for HTTP APIs

Saturday, 14 April 2012

HTTP APIs

When you’re designing HTTP APIs, you need to keep a lot of concerns in mind. Stealing a page from XP, let’s look at some possible personas and their user stories for HTTP-based APIs:

Joe at HugeCorp

Let’s start with the people who consume the APIs. Joe uses Java (or some similar statically typed language). He’s used to having good tool support, with IDEs that manage all of the sticky details for him, and language features that keep him out of trouble. Joe may not be able to adopt new things easily; HugeCorp is set up to follow what it believes are “best practices”, even if they trail the rest of the world by several years. When he looks at your API, Joe will need crystal-clear documentation for it, with examples in his language — and ideally tool support — easily available. He’ll also likely want a “contract” locking in all aspects of the API, including the URIs and payload formats. While these things are generally considered bad practice on the Web because they make the interface tightly coupled and therefore brittle, you’ll need to address his concerns somehow — most likely with some “language bindings” for Java and perhaps C# as well.

Mary at StartupDotCom

Mary, on the other hand, works at a startup that’s moving fast. She doesn’t have time to learn complex APIs or new tools, preferring things simple and dynamic. She probably uses Python, Ruby, Scala or JavaScript, and is very comfortable rolling her own tools, although she’d prefer to reuse existing ones, provided that they’re well-understood and not too bloated. Understand, though, that she’ll view “language bindings” with some suspicion. Mary might be a bit of a fashion victim, in that she’s interested in new trends, but if she does her job well, she’ll focus on results; her company doesn’t have the time or resources to indulge in too many flights of fancy. When Mary consumes your API, she’ll probably be using some basic HTTP and JSON tools provided by her language of choice. She won’t want to use any schemas or other heavyweight tools, and will expect your API to be simple enough to get productive with in a very short amount of time.

David the Mobile Developer

David is developing mobile applications that consume your API. While smartphones are getting more powerful all the time, he still has to worry about memory and CPU constraints, and also doesn’t want to chew up too much battery just to parse a big response. Furthermore, the HTTP libraries that he’s using might not have all of the features and capabilities of their bigger brothers.

Bruce the Really Badly Connected User

Bruce doesn’t write code that uses the API, but he does use software that calls it. He lives in a place that’s not well-connected to your API server; it might be in the Australian outback, or on a mobile network with lots of packet loss. He may even be using a satellite connection to access the Internet, which introduces a lot of latency. Bruce’s network connection may go down periodically as well. Helping Bruce means assuring that your responses aren’t too big (compression helps), that the granularity of their sizes makes sense (more requests introduces more chances for dropping packets), and that caches can be used where possible.

Paul the Busy API Developer

Now, let’s switch viewpoints, to the people who help get your API out there. Paul is the developer actually implementing the server side; he wants a clear specification that doesn’t have lots of options or features that won’t get used. You can help Paul by keeping your API simple and making sure that he doesn’t have to implement too many new things to get it done. Of course, factoring the API correctly so that it can be mapped to the underlying system is good for Paul too.

Gigi the Tester

Gigi performs QA on Paul’s work, and needs easy, repeatable ways to assure that it’s working correctly. She needs a way to assure that the API does what it’s supposed to, and for that she needs a well-written, unambiguous, stable specification for it. She needs to be able to log bugs on the spec as she finds issues, and the spec needs to be not just precise, but accurate.

Steve the Performance Engineer

Steve’s job is to make sure that the API is as fast and as scalable as possible; if it goes down because of a spike in usage, it’s his fault. He’ll want to use caching for it, and will need the URLs used to be distinct enough that he can track down performance issues.

Jim the Evangelist

APIs need to be explained to other people, and this function falls to Jim. He’ll help write documentation, sample code, and generally “sell” the API so that people know about it, want to use it, and tell their friends about it. Making Jim happy means giving him an API that’s as simple as possible and that people can intuitively use. He’ll likely want to create “bindings” for some languages, which means that he’ll value an API that’s stable and extensible; he doesn’t want future changes to break old customers, because he’ll end up dealing with the mess.

Allan the Support Engineer

Once the APIs are built, deployed, evangelised and adopted, there will inevitably be problems. Allan is charged with finding the source of problems. One of the key tools available to Allan is the API server’s logs; if the URLs are well-structured and an appropriate amount of information is logged, he’ll be able to see how people are using the API and find their problems.

Angie the Tool Developer

Other folks are going to be affected by your API design as well. Angie builds tools that might interact with your API; for example, a validation tool (like REDbot), a spider, or a IDE plug-in. Angie doesn’t want to tailer her tools to just your API; she wants to be able to cover a lot of APIs with just a bit of code. Helping Angie means adopting common patterns, so that she can write to the patterns, not your specific API.

Jorge the Extension Developer

Finally, Jorge wants to write an extension to your API. He might be work for another part of your company, work for a partner company, or be completely unrelated. In any case, he needs to be sure that his extension won’t clash with your API, and that likewise your API won’t stomp over his extension in the future. Helping Jorge means having crystal-clear documentation of your expectations for his extensions. By extension, that means you need to document the expectations you place on clients for consuming those extensions too.

Obviously, not all of these always apply, but I found the exercise helpful. What other personas can you think of? What other things do these folks need?


3 Comments

John Knight said:

What about an Ops/Devops role for monitoring, scaling, etc.?

Saturday, April 14 2012 at 8:12 AM

Mike Pittaro said:

You can add Inga, the Integration Developer.

Inga works with many API’s simultaneously, not just your API. Inga will probably only look at your API documentation once, and may not revisit it for a long time. Inga is interested in the data, often has to translate it, and doesn’t like surprises. Inga values simplicity and consistency over creativeness. If you are returning a UTF8 document, don’t slip in fields from somewhere else containing MS-1252 data - she needs to reliably convert code pages between systems. Use ISO standardized date formats - guessing what 08/04/02 means is not her job. Inga often works with large data sets, so make sure your API works with larger requests, and supports a reasonable paging model if that is appropriate. And most of all, never, ever return a 2XX Success code, with an error in the body instead of the data Inga expects.

Saturday, April 14 2012 at 12:12 PM

Jan Algermissen said:

“JOE AT HUGECORP” is symptomatic for the whole issue of REST’s potential not being leveraged. The answer to this comes down to how the sole knowledge of the relevant bunch of media types can be used to meet Joe’s needs.

Because if we give Joe more that just the media types, we could equally well give hime WSDL :-)

Saturday, June 16 2012 at 12:04 PM