Ask the Princess: Episode 1

This is the first in a series of posts entitled “Ask the Princess.”  I am a princess and a polymath, and I’ve got lots of opinions and experience around various things.  Topics covered here will be mostly about building APIs, but can cover martial arts, parenting, politics, or anything else anyone chooses to ask me about.  Bring it on, I’ll answer with all the information and snark I can summon for your topic.    Without any further introduction, here’s the first column.  The questions and answers are both mine.  Send me an email or tweet with a question and I promise to address it in a future column.

Who are you, and why should I listen to your advice?

I’m Princess Polymath, and I’ve had a lot of experience as a developer, an evangelist, a mom and, well, a human. I have insight and experience to share, and lots of snark to season it with.  If you’re a developer or consumer of web APIs my questions and answers should be particularly useful to you, but I’m aiming for columns that are funny and fun for any humans who care to take the time to read them.  My goal in life is to entertain, engage, and help people to get past frustrations – and this seemed like another good tool for my tool belt.  But since I’m asking my own questions, let’s start with something easy.

I’ve got a great API but haven’t had time to make any documentation.  I want to release it right now!  What do you think?

APIs aren’t like other products.  If a developer comes to use your API and ends up with a poor experience, they’re unlikely to ever come back.  Remember that a lack of documentation, without any context for how it’s expected to work, can and will result in an extremely frustrated developer, and they’ll do whatever they can never to use your system again.

To quote a trite but appropriate cliche, you only get one chance to make a first impression, and in the world of APIs the bar is high for a great first experience.  Developers can get frustrated easily, and have little patience for someone who doesn’t value their time and energy.

Make the documentation.  Create some tutorials.  Write and show sample code, and be available to give good support to your developers.  Show them that their time is important and valuable to you and they’ll pay you back by becoming advocates for your system within their community.

I have a fantastic idea for an API.  I whipped it up last night, and it’s awesome!!!  Why isn’t my manager excited about it?  It’s totally not fair 🙁

Sorry, I’m siding with your manager here.  You made an API… to solve what problem?  What is the purpose of the API?  Creating additional interfaces into your system without understanding what they should be used for is really not gonna make for an excellent product.  Your API has to be a first class product, and I’m sorry to say that skipping the steps of figuring out the business value and use cases, and how you’re going to measure success mean that what you’ve created is a toy, a hobby, and not a product the company will want to support.

If you’re certain that your API is super awesome, you can actually back into the right information by figuring out use cases for your API and creating prototypes for them.  Then determine what value this product can have for your company.  APIs don’t have to create money from thin air – many of them aren’t even going to increase monetization – but they can make your main products better, more appealing, more accessible to your customers.  You can improve the user experience, keep partners more engaged, and create more love and attention for your company’s system.

Just imagine you’re trapped in an elevator with your CEO and you’re trying to explain why you have an API – and that “Because… API!!!” isn’t going to fly.

You have a lot of things to say about irresistible APIs, but my API is only for use inside of my company – the developers are forced to use the system and so I don’t have to worry about their “Experience.”  So thanks for the thoughts, but I don’t need them.

Ok, sure, you can think that way.  But let me just tell you that in my experience, people who are forced to do something that’s unnecessarily difficult tend to become very recalcitrant – nobody wants to be told how they have to achieve a goal.  Sure, they’ll use your system, but a poorly designed API will cause them to try to figure out how to achieve their goals in whatever way they can, and they’ll likely end up pushing the edges of your system to try to achieve their goals, cursing your name the entire time.  Without excellent documentation they’ll waste time attempting to figure out what the system needs to function.  Without example code or tutorials they’ll use the system in ways you likely don’t expect.  All of these will create a much larger support burden for your team, and worse yet, these developers likely have the ability to escalate to your management chain and create trouble for you in the future.  Take my advice, make a system that’s straightforward, well documented, and simple to use, and save yourself the headache and heartache of having to support cranky developers who have no choice but to use your system.  Plus, maybe they’ll give you beer.

As a favor to my users, I’ve created convenience API resources like “latest” for the most recent item in a list, but they are whining that redirects aren’t usable with complicated authentication schemes.  What’s *wrong* with these people???

What’s wrong with you?  My apologies, but there are two different ways to approach problem solving in the development world.  You can make things easy for yourself, but hard for your users… or you can do the opposite.  One major goal of web APIs, REST in particular, is to create a system that’s simple for developers to use for integration and automation.  Since you’re working to make the system accessible for developers using different languages, frameworks, or platforms, you need to keep this goal at the top of your priority list.  Don’t get lazy – even though it may take a little longer to do the right thing, not doing the right thing can create a support nightmare.

For instance, in this case, a call to /my/resource/latest can act in one of two ways (from the developer’s perspective).  In the simplest case, they make the (signed) call to the latest endpoint and get back the correct information, likely with information about the resource’s actual URL.  One call, getting the data back, just as the developer would expect.  You’ll find that I yammer pretty constantly about making sure you don’t surprise your developers – much as UX experts talk about how important it is not to surprise your users.  In this case, the developers are your users, and making them make two separate calls is certainly not what they expect.  It seems like it’s not a big deal, but consider the following:

• It’s not a convenience method if the developer has to write code to make a second call.  They might as well get the list to find the last member and then pull the correct resource.  You haven’t created a “convenience” method if it requires the same amount of effort as existing resources, and you’ve created an incorrect expectation by apparently offering something easier – which isn’t really.
• More importantly, this process (making a call, getting back a redirect and then signing/making a second request) is *more* work than the more standard approach I described above.  Most HTTP libraries can handle 302’s with grace, but many won’t know to re-sign the request with the authentication scheme when making the second request.  So now, the developer who was able to use a standard library for their language has to update it to add new functionality

So, no.  Making convenience functions or resources is a great idea – but consider carefully how people will use those resources and make sure that your implementation makes it easier for your users to access the system.  In this case, your server should do the work, not the client.  Find the resource represented by “latest” and just return that to the client.  Problem solved!  Yes, it’s more work for you, but a little extra work on your part will save a lot of time and heartache for your users.

Ask the Princess

So here you have it, Ask the Princess.  You are welcome to ask me questions about *anything*.  Programming, fitness, data, martial arts, cooking, APIs, anything at all, and I will do my best to answer them in a way that gives you what you’re looking for.  Send questions to me at @synedra on twitter or post them here as comments and I’ll write another column when I have enough questions.  Or when I’ve put together enough of my own questions and feel like writing some more.

Thanks for your time, and get out there and make something amazing!