Brail’s Blog

I have been working on some applications recently that include a traditional web app component as well as an API. This has reminded me of what I think is a key design principle for building APIs, namely this: APIs are different from web applications. You should treat them differently and deploy them as separate components.

To run a modern web application, you need:

• Session-based login, so that you present a nice, pretty “login” screen
• Session state, so your customers can store their shopping cart and whatever else you need
• A presentation framework like JSP or JSF
• A navigation framework like Struts
• Stylesheets
• Static content

To run an API, you don’t need or want any of that stuff. 

For instance, session-based “login” pages are the norm for web apps today because they look nicer than the “password” dialog box that your browser puts up when you use HTTP Basic authentication.

Many APIs have also been written that use this paradigm — there is a “login” method that takes a username/password and returns a session token that the client must use for each request. I suspect that this is common because it is how the original web application was written and the developers figure it was easy to use the same paradigm, or perhaps it wasn’t even possible to expose the back-end services in any other way because the web app was baked together long before an API was conceived.

(Or perhaps API builders think that this is more efficient than validating the password on each request. But why? You have to validate the session ID anyway, or at least you better do that, and if validating a password is causing performance problems then perhaps you need a better app server.)

While this pattern is fine for a web browser, it makes your API more difficult to use because now the API client must remember that session id. It also makes it more difficult for proxies and other types of intermediaries because they may have to remember the session ID too. And since every API has a slightly different “login” method and a different way of retrieving and returning the session ID, there’s no standard library that the API client can use to make all this happen automatically.

On the other hand, an API that uses HTTP Basic authentication is easy to use and you can invoke it in lots of ways, from Java code to “curl” on your command line.

Session state is another difference between a good web application and a useful API — it’s crucial for humans using your web site, but does your API need it? It will be called by other computers who can remember what you tell them to remember. If your API is stateless, then you’ll have an easier time scaling it up, because session state introduces complexities to the load balancing layer, and if you want it replicated for high availability, to the app server layer too.

Furthermore, all the other “stuff” that you will deploy in your web app server in order to run a web app is, if anything, a detriment to the API. Frameworks like Struts, JSF, etc. use memory and disk space.

While we’re at it, think about those good old “three-tier architectures” from the 1990s. The whole point was to separate presentation and business logic. That was a good idea! If you’re building a web app and an API at the same time, it also makes sense to use the API as the business logic back end if you can.

So, if you can do that, then you will be probably releasing the web app component and the API component on different release schedules — which will be easier if you develop them, manage them, and deploy them separately.

What does this mean in the end? For a small application, perhaps this just means that you have two WAR files (or whatever you use) — one for the web app and another for the API. For a larger deployment, a good idea is to set up a separate DNS entry for your API, so that “api.mycompany.com” is different from “www.mycompany.com”. Perhaps at first these will both point to the same IP address, but over time you have the flexibility to change this if you wish.