11436 SSO

API Design: Are you a Pragmatist or a RESTafarian?

Brian Mulloy
Nov 08, 2011

I wanted to write some posts on RESTful API design best practices we've observed over the last year. First, let's start with our overall point of view on API design.

We advocate pragmatic, not dogmatic REST. What do I mean by dogmatic?   

You might have seen discussion threads on true REST - some of them can get pretty strict and wonky. 

Mike Schinkel sums it up well - defining the RESTafarian

Our view: approach API design from the "outside-in" perspective.

This means we start by asking - what are we trying to achieve with an API?

The API's job is to make the developer as successful as possible.   

Why? Look at the value chain below - the developer is the lynchpin of our entire API strategy.

So design the API to maximize developer productivity and success as the primary design principle.  

This is what we call pragmatic REST.

Pragmatic REST is a design problem.

You have to get the design right, because design communicates how it will be used.

So now the question is  - what is the design with optimal benefit for the app developer?

The design asethetic for APIs is to think about design choices from the developer point of view.

This is pretty much the guiding principle for all the specific tips that we'll dig into next.

Next time: considerations in designing your base URLs.

Creating World-Class Developer Experiences