Saturday, 14 April 2012
User Personas for 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
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?