Four Ways to Make Your API More Enjoyable to Use
3 min read
Jon Ursenbach

Lead API Engineer

Four Ways to Make Your API More Enjoyable to Use

At ReadMe, we love APIs, and we love them even more when they get whimsical—so much so that it’s part of our company’s mission. The problem with APIs, however, is that they can often be business up front without the party in the back.

How can we make APIs fun? Let’s look at some unique ones that are all party:

  • Dog API: I was made aware of this when a candidate was working on a project they brought in, and happened to be using this API in order to show a random picture of a dog on a page. Did you know that there is a dog breed called Affenpinscher?
  • The Star Wars API: This is an API that lets you query information from the Star Wars film universe. Much like Content-Type headers in APIs, you can supply ?format=wookiee to translate the response into Wookiee. Alright, it’s not quite Shyriiwook, but it’s still fun!
  • An API of Ice And Fire: Much like the Star Wars API, but covers the entire A Song of Ice and Fire book series. Perhaps you can create a Markov chain using the data from this API and finish The Winds of Winter before George R. R. Martin does?
Screenshot of map showcasing pinball machines in Austin via the Pinball Map project
  • Pinball Map: This is incredible. Not only can you see a list of every pinball machine ever, and their currently tracked high scores (!), but you can also query where they’re located so you can go out and play them. Unfortunately for us, the best machine, Data East’s Batman (1991), is a 50 mile drive from ReadMe HQ. Time for a company outing? 🤔
  • PokéAPI: Built by the same person behind The Star Wars API, this is an entire API devoted to the Pokémon video game series. It even goes so far as to have dedicated endpoints for each games’ Pokédex, allowing you to query all of the Pokémon for a specific game. With this you could build a Slack bot that lets you play Pokémon! Build out a database that stores the users’ inventory, set up virtual shops (/pokemart buy pokeball 5), and battle and catch random Pokémon. Imagine “A wild Snorlax has appeared!” appearing in a channel and having to race with everybody else in the room in an attempt to be the first to catch it (/throw “great ball”).
  • AmiiboAPI: Super neat compilation of data on Nintendo Amiibo. Did you know that Nintendo has released 559 of these things on NFC trading cards? I didn’t!
  • Bacon Ipsum: Lorem ipsum, but what if it were all pork products. Spicy jalapeno bacon ipsum dolor amet pork belly tri-tip rump turducken flank capicola burgdoggen buffalo boudin drumstick landjaeger pancetta shankle short loin? Indeed.
  • Noops: A rad collection of puzzles where you take APIs they give you to make “machines” (Noops) do things. In one example, you can generate a random maze, write code to solve it, and use the API to feed instructions to the Noop to get out of the maze.

Now it’s your turn:

Okay, so maybe you can’t make your API quite that whimsical, no matter how much you’d like to return random pictures of dogs. But what are some things you can do with your company’s API to inject life into something that might otherwise be a bit mundane?

  • Easter eggs: Everyone loves a good easter egg—whether a unique response format like Wookiee, or the ol’ reliable Konami code—you can add a fun hidden easter egg into your API that when discovered will give the person using it a good chortle. Maybe you could support a text/morse-code media type and that translates all strings to morse code?

    — .- -.. . / -.– — ..- / .-.. — — -.-

  • Emojis: Oftentimes a well placed emoji in your API documentation can help make things stand out in ways that they might not have previously. Have a deprecation notice? Prefix it with ⚠️. Calling out some important information? Slap an ℹ️ on there. Link to your support knowledge base? 🆘 (Be careful not to overdo it though!)
  • Support your API consumers: If you have a public API, do your best to support the people who use it. When companies launch their documentation on ReadMe, we give them an option to let us mail them a confetti cannon. Is there something you can do when somebody makes their first API request? Their millionth?
  • Make things that just work: APIs don’t have to be whimsical to be fun. Often it’s the most fun if things end up working as you expect them to. Have an API endpoint that returns a JSON representation of a page on your website? What will happen if I make an API request to that with an Accept: text/html header? What about if I append .html to the end of the URL in my GET request?

We work with APIs all day, every day. Anything we, as API owners, can do to make looking at JSON all day a bit less monotonous, by adding a sparkle, laugh, or smile, can help to make another developer’s day a bit brighter.