API Framework Requirements
In Web API Versioning we mentioned in passing that we’ve been developing our own, miniature web application framework specifically for easily building web APIs. Today, we’d like to present the rationale and feature set in more detail.
If you build a new web-based application, chances are you’re going to reach for Rails or Express, because they’ll get you started quickly. But there’s are a number of drawbacks with doing that, which tend to manifest themselves only partway into your project.
The Rails Perspective
Rails is fantastic at getting you up and running quickly, in that the resource model it uses implicitly offers RESTish APIs for everything you can manipulate in the web browser.
Author’s note: The term RESTful is usually misapplied when talking about Rails. REST requires that requests must be stateless. Rails itself provides these facilities, but pretty much every application implemented in Rails maintains session state server side. We use the term RESTish instead to denote this difference.
Rails’ ability to get you running quickly starts to become a constraint when you want to provide truly RESTful request endpoints, as any request handling is tied to an object that is usually automatically reflected into a database.
Similarly, it becomes clear very quickly that not every resource should be exposed via an API, and not everything exposed via an API should be viewable in the browser within an HTML template.
The Express Perspective
But you’ve got to do everything yourself here. Want to support different request or response formats for an API call? Code it by hand.
The API Perspective
If you set out to build even a marginally scalable new app, in this day and age you have to consider that there will be more than just the browser as a client. You may solve your mobile needs with a responsive web UI, but more often than not, a native mobile app with different user experience from the web UI is desired.
With that in mind, it becomes clear that your web UI and your API calls must scale to different user numbers. More specifically, your API will likely need to scale to many more users than your web UI.
When you realize that, your application architecture will likely start treating the web servers that serve API requests quite differently from the web servers that serve web UI requests.
Add to this that most successful web applications offer the API up to third-party developers, and your API becomes your product. From there on it makes sense to choose the technology stack for your API more or less independently from the stack for your web UI.
There are a bunch of features that make a web application framework useful for writing APIs:
- As previously noted, versioning facilities make the lives of developers much easier.
- Protocol Agnostic
- The last thing you want to do is deal with those request and response formats; instead you’ll want to concentrate on just writing functions.
- Support Request/Response Formats
- You likely don’t want to prescribe these formats to clients, or rather offer them some choices.
- Any good API is documented. Wouldn’t it be great if your framework exposed the API documentation to outside users?
- In today’s “HTTPS everywhere” world, we have a slightly better understanding of the fact that some things must be protected. It’d be great if a web API framework enforced HTTPS and even HTTPS client certificates for functions you want to protect.
- Multiple Components
- For scalability reasons, it makes sense to serve different APIs from different machines, but on a smaller scale that can be cumbersome. A good framework should allow you to serve multiple independent APIs to overcome that.
- As APIs need to support many more users than web UIs, good request performance is a must.
- Last but not least, nobody needs a framework that has thousands upon thousands of lines of code. Let’s keep things simple.
All these things have made it into our own little API serving framework, because quite frankly, nothing out seems to quite satisfy these requirements. We’ll be talking about that a little more in future.