Going Beyond Just Documenting Your API, And Making Things Fun

I look at a lot of API documentation, something that until recently has been pretty static--pun intended. As an API consumer I really appreciate standardized approaches to documenting an API, like using Swagger or API Blueprint, but I also really enjoy when people go the extra mile to add little details, that make the experience a little more fun.

A recent example of this is from the Spotify API team. When it comes to the search endpoint for the Spotify API, they put in this little addition:

The field filter tag:new can be used in album searches to retrieve only albums released in the last two weeks. The field filter tag:hipster can be used in album searches to retrieve only albums with the lowest 10% popularity.

I love shit like this. It makes the often mundane world of APIs, a lttle more bright. It shows that there is a human beneath the very technical story that is often being told as part of API operatoins. 

I don't about you, while I enjoy the self-service nature of APIs, where I don't have to deal with people and sales teams to be able to put a valuable resource to usee--I also enoy knowing there is a human behind the scenes. Especially if it someone who cares enough about an API enough to have fun, and enjoy themselves along the way.