Bad API Docs and The Quest for the UPS API

John Musser
Apr. 10 2008, 02:46AM EDT

Can dealing with a difficult API provider be like trying to solve the puzzles in a classic text adventure game? In an amusing blog post entitled The Quest for the UPS API over at Ruby Discoveries and Idioms, the trials and tribulations of dealing with the United Parcel Service API has been parodied as an old-school adventure game. And as any developer who has had to navigate some of the more onerous API sign-up processes or unclear and overly complex documentation can attest, this may seem familiar. As the introduction notes:

I'm inspired by the hoop-jumping UPS (yes, that UPS) requires for developers to begin using their web service APIs. There are NDAs involved, so this is not about the APIs themselves; it is about getting to the point where one can start working with the APIs. It is presented in the format of a text adventure. Pedantic corrections to format are welcome, since it's been a long time since I've played one.

And the game itself? Here's a snippet that gives you a sense of how it goes:

Welcome to Colossal API Quest! Find the documentation, get authorized to use the development integration environment, and meet the needs of your client to achieve fame and fortune!

  • You are in a maze of twisty little passages, all alike. There is a door to the North.
  • N
  • Welcome to UPS. A GATEKEEPER blocks the door to the North. There are also doors to the East, West, and South.
  • talk to the gatekeeper
  • "Username and password or register?"
  • say register
  • "Tell me everything about yourself. Also, what is your UPS account number?"
  • N
  • "Username and password or register?"
  • E
  • Welcome to UPS. There are several signs here advertising the wonderful web services UPS provides and pointing to the door to the North. There is also a door to the West.
  • N
  • The door is locked.
  • W
  • Welcome to UPS. A GATEKEEPER blocks the door to the North. There are also doors to the East, West, and South.
  • W
  • Your CLIENT is here. There is a door to the East and to the West.
  • talk to the client
  • "Is my website ready yet?"
  • need UPS help
  • What?
  • say "need UPS help"
  • "You should talk to our UPS contact. She's in the next room."
  • W
  • There is a notepad in an otherwise empty room. There is a door to the East.
  • get notepad
  • You can't take that.
  • look notepad
  • It says, "Sorry, I'm on vacation for the next 6 turns. Please leave a message."

And this is only the first part of the adventure. API providers might take notes here on what not to do.

John Musser

Comments

Comments(3)

User HTML

  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.
  • Web page addresses and e-mail addresses turn into links automatically.

[...] Bad API Docs and The Quest for the UPS API And this is only the first part of the adventure. API providers might take notes here on what not to do. (tags: blog.programmableweb.com 2008 mes3 dia10 at_home games humor webservices blog_post) [...]

AMen, if only there were a way to automate API documentation it would make the life of a mashup web developer very happy...