API Blank Slate

Doug Breaker  on May 12, 2011

A couple of years ago I went to Argentina. I don’t speak Spanish. This meant a lot of the basic conversations I’d have with locals were frequently interrupted by me paging through a translation guide. I felt very disconnected: basic exchanges were cumbersome.

When I work with an API for the first time, it often feels the same. A lot of my time is spent referencing documentation just to get basic things working. That’s asking for a lot of effort at this stage of the relationship. I just want to know: is there chemistry between your API and me?

Spending a lot of time trying to get my first method call working is frustrating. When we built the Scout API, I wanted to make that initial experience easier.

Parameter-free methods

When pulling metrics from Scout, there are 8 possible parameters (name of the metric, the server id, group id, etc). A method like this would be intimidating:

Metric.calculate(name,function,aggregate_function,plugin_id,server_id,group_id,start_time,end_time)

Through trial and error, it might take fifteen minute just to pull your first chunk of data. I wouldn’t put you through that. Instead, you can grab sample data very quickly:

> Metric.first.average
=> {:name => “Memory Used”, “value” => 500.0, :units => “MB”}

Realistically, would you just pull the first metric and display its average value over some unknown time period on your business dashboard? Not unless you’re this guy. However, it lets you get started in a natural way.

Embrace instincts

Traveling again a couple of years ago, I played basketball with a group where I was the only one that spoke English. Unlike directing a taxi driver in Spanish, this was easy. We picked teams, called fouls, and patted each other on the butt just like we do in the United States.

The game was the same. At Scout, many of our customers have used Ruby on Rails before. Notice the similarity between finding records with ActiveRecord and the Scout API:

# Rails
> Criminal.first
=> <#Criminal name=”Butch Cassidy” id=999>
# Scout
> Server.first
=> <#Server name=”Web Server #1” id=555>
# Rails
> Criminal.all(:conditions => “name LIKE ’Capone’”)
=> [<#Criminal name=”Al Capone” id=100>]
# Scout
> Server.all(:name => “DB”)
=> <#Server name=”DB Slave #1” id=400>
# Rails
> criminal.prisons.all(:conditions => “name = ‘Alcatraz’”)
=> [<#Prison name=”Alcatraz” id=12>]
# Scout
> server.metrics.all(:name => “Memory Used”)
=> [<#Metric name=”Memory Used” id=333>]

It’s designed to feel like something you’ve done before.

Designing a usable interface is an art form, whether it’s a web page or an API. Developers like myself may lack visual design skills, but designing an approachable API is within reach.