Bad API Docs and The Quest for the UPS API

John Musser, April 10th, 2008

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.

Tags: Issues, fun
Both comments and pings are currently closed.

3 Responses to “Bad API Docs and The Quest for the UPS API”

April 10th, 2008
at 10:33 pm
Comment by: RezIt

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

April 11th, 2008
at 4:38 pm
Comment by: rascunho » Blog Archive » links for 2008-04-11

[...] 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) [...]

October 1st, 2012
at 1:24 pm
Comment by: Jesse

Try out Postmaster, it’s a simple REST API for UPS, Fedex, and USPS.

Follow the PW team on Twitter

ProgrammableWeb
APIs, mashups and code. Because the world's your programmable oyster.

John Musser
Founder, ProgrammableWeb

Adam DuVander
Executive Editor, ProgrammableWeb. Author, Map Scripting 101. Lover, APIs.