What Makes a Good REST API Framework?

Luc Perkins

July 16, 2014

Share +

What are some of the best practices used to create a Good REST API Framework? Read on to find out.

A few years ago, the world of web development was crazy about new web frameworks. "Hey everybody, check out my new framework! It does cookies, headers, status codes, the whole deal!" While this excitement made sense at a time when there weren't a lot of options beyond ASP.NET, crufty Java frameworks, PHP, and a still-nascent Ruby on Rails, web frameworks don't generate the same kind of excitement, and rightfully so. Instead, the focus has shifted to abstraction layers on top of HTTP frameworks.

REST API libraries are one of the most common abstractions that we now see built on top of traditional HTTP frameworks. What puzzles me, however, is that I find the discussion around REST API libraries to be somewhat lacking. Whereas you can find all kinds of HTTP framework comparisons, best practice-related discussions, and so on, I don't see REST API frameworks getting the same treatment. So I thought I'd get the ball rolling by delving into what makes a good REST API framework and providing a shortlist of what I take to be exemplary frameworks.

What Makes a Great REST API Framework?

While REST API frameworks vary a great deal in terms of what they offer, it'd be hard to consider a framework to be any good if it didn't

Versioning

This is one is pretty basic but nonetheless important. When exposing a REST API to the outside world, it's important that you don't change the core API incrementally and without fanfare, as that's a good way to break applications (if not businesses). Instead, any API changes should be grouped together and introduced via version changes. We've all seen REST APIs with routes that are prefixed with /v1/ or /v1.0/, for example. A good REST API framework allows you to accomplish this in a programmatic fashion without having to go back and modify all of your routes one by one, as many HTTP frameworks would do.

Resources rather than routes

If you're building something simple and want to produce your API on a route-by-route basis---e.g. GET /posts, GET /posts/:id, POST /posts---and define the logic associated with each route, an HTTP framework will usually be enough. But this can be unnecessarily burdensome. In many cases, it's easier to construct a resource---e.g. Post, User, Meetup, Tweet---define what it means to perform CRUD operations on that resource, register that resource, and have the routes created for you. A good REST API framework should abstract away route definitions while leaving things like database interactions (ORM-based or otherwise) in your hands.

Easy authentication

While there are some REST APIs that provide public information only---the Marvel Comics API is my favorite example---most need to enable users to perform API interactions securely, whether via basic or digest auth, OAuth, or something different. A good REST API framework should make it easy to implement your own authentication logic and to apply that logic to your API's resources. Instead of being forced to sprinkle authenticate_user( ... ) functions all over your routing logic, as an HTTP framework would do, you should be able to define your authentication layer at the resource level.

Form body parsing

Most REST APIs nowadays accept multipart form data as a means of inputing new information, as in this API call:

curl -XPOST
-F name=Luc
-F age=32
-F profession='technical writer'

Parsing multipart form data on the server side can be a hassle, often demanding a complex if/then logic for parsing through key/value pairs in a way that maps onto resources that you've defined. A good REST API framework should make this very simple, allowing you to define which form fields must be present to create a resource and which data types the values of those form fields should be.

Documentation generation

Let's face it: an undocumented REST API is no good. If you're REST API is public facing, it needs to be documented so that people can build meaningful things on top of your services. And even if your REST API is used only internally as part of a service-oriented architecture, people within your organization need to feel at home in your API. One way to document an API is to do it the old-fashioned way, i.e. to REST API documentation can be a beautiful, inspiring thing. Personal favorites include Stripe and Parse. A good REST API framework should enable you to go from zero to decent documentation with as little effort as possible.

Stay Tuned

In this post, I've provided a list of things that I take to be essential for any REST API framework worth its salt. I'd love to get your thoughts in the comments. Anything I'm missing? Anything that I've listed here that should be left to HTTP frameworks instead? Any examples you'd like to share? Thanks for reading, and please, don't hesitate to give us your feedback.