blog

Let's talk about testing

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:

Versions
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.
Documentation
Any good API is documented. Wouldn’t it be great if your framework exposed the API documentation to outside users?
Security
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.
Performance
As APIs need to support many more users than web UIs, good request performance is a must.
Simplicity
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.


Comments are closed.

Reputation. Meet spriteCloud

Find out today why startups, SMBs, enterprises, brands, digital agencies, e-commerce, and mobile clients turn to spriteCloud to help improve their customer experiences. And their reputation. With complete range of QA services, we provide a full service that includes test planning, functional testing, test automation, performance testing, consultancy, mobile testing, and security testing. We even have a test lab — open to all our clients to use — with a full range of devices and platforms.

Discover how our process can boost your reputation.