The Three Tenets of API Design (1/3): Be Boring

This is an extract from my book “API on Rails”.

  1. Embrace HTTP
  2. Respect REST

T1: Be Boring

Ideally, a consumer of the API should never be surprised by how you handle things — while this is rarely the case in a real-world scenario, you should still aim at creating something that’s as reproducible as possible. A good rule of thumb is that people should never be inspecting your response to figure out how to get what they want: they should just know.

Consistency

This requires some initial work, but should be easy to follow once you get things rolling.

{
"error": "error_type",
"error_message": "A human-readable description of the error",
"meta": {
"additional": "info"
}
}
class PostsController < ApplicationController
def create
post = Post.new
if post.save
render status: :created, json: post
else
render status: :unprocessable_entity, json: post.errors
end
end
end

Documentation

You know what’s really boring? That’s right, documentation.

Technology leader and strategic advisor. I work at the intersection of people, software and words.

Technology leader and strategic advisor. I work at the intersection of people, software and words.