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

Express in contrast with Rails just provides the bare minimum of request routing, mapping a relative URL in the server to a JavaScript function. You can use a template engine to render HTML, or you can output any other format more suitable for API endpoints.

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.

Desired Features

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.

Written by: Mark Barzilay

Graduated with honors from TU Delft in 2007 studying Electrical Engineering and Media & Knowledge Engineering. Founded spriteCloud in 2009 and worked on test automation ever since, helping out small and large companies with their test automation strategy and infrastructure. Mark is also leading the development on Calliope.pro, an online platform for all your automated test results.

Subscribe to our mailing list!

Stay up-to-date on all things quality assurance,
test automation, and cybersecurity.

We’re spriteCloud, a leader in software and cybersecurity testing.

Aside from interesting articles, we also have a team of software testers that can help your organisation.

Have a look at our testing solutions.