Kristo Vaher

API-centric design

Web development has been slow to catch up with desktop programming over the years. Large part of this reason is because web is built around HTTP, which is technically a ‘stateless’ protocol. But modern web applications are often anything but stateless and consist of layers upon layers of session handling and asynchronous requests to overcome the inherent weaknesses of HTTP. One of the better principles for handling all this mess is the API-centric development.

API-centric development is nothing new for software development in general. It originates from desktop software programming. But what is API-centric principle and how can it apply to web development?

Majority of web applications today get the whole Model-View-Controller pattern wrong. In an MVC pattern the Views should consist of both UI components themselves and the UI logic, but in web development the views are only that in name: websites implement Views as an entire ‘page’ HTML as a template or a procedural script. MVC Controllers should just be user actions and input data validations, yet in web development controllers are a vague entity that tries to do anything from AJAX to event handling to form submits and are often tightly coupled with Views. MVC Models – which are technically object representations of database rows – are the only thing that modern web development usually implements correctly in most places, but reality is that a lot of web services don’t implement Models at all.

Web development today becomes even more troublesome once you raise the topic of API’s – Application Programming Interface’s. API’s are a way to use software without interacting with software through a dedicated user interface. In a way it is similar to running software through command line: you write a command, add parameters, execute and get a response. You have likely heard about API’s before, as they have become an important topic for widely popular social networks from Facebook to Twitter and LinkedIn. A lot of social games and widgets are developed thanks to those API’s.

Reality is that most web software today is developed without thinking too much about API’s. From my personal experience I can say that, as a general rule, web services and applications do not get API’s developed for them before there is a sudden need for it. This results in a situation where a lot of software ends up with API’s that are added as a separate layer, plugin or an extension that needs to be maintained separately. And this layer is then made to work over HTTP.

This seemingly intimidating mess happens because API’s are thought of as something that adds to the cost of developing software. There have been too many examples where the introduction of API’s push the already limited development budgets beyond limits. And this is true – but only if you develop software by considering API’s as something extra: a layer, extension or a plugin.

How to go about this issue differently?

Every web service – even a website – can also be programmed by developing the API first. This means that the entire functionality can be planned from the perspective of API from day one. What are the functionalities of your application? What items have to be viewed, added, edited, deleted? Does your software have users and what permission-checks need to be implemented?

Planning your software in this manner is not all that different from before, the only main difference is that you must not think about the User Interface – at all. Your software functionalities are still the same, it still needs to do things A, B and C. This helps you to iron out most of the MVC-from-desktop-to-web kinks that are often caused by the UI getting in the way.

The entire functionality of a web service should focus all of its development early on to develop these three things:

• Models - database object representation, your users, products, pages and so on
• Controllers - functionality and method calls that give a specific result, sometimes involving models, sometimes not, for example methods to get all products from database
• API gateway - script/class which can be used to execute controller calls, this should be available within PHP as a class as well as over HTTP – since you want the API to be available from anywhere.

Once your gateway is developed and Models and Controllers are set, then your entire web service should be 100% functional. If you build a Twitter client, then you should have log-ins, tweet submits, tweet reading and so on. If you planned an e-shop, then you have Models for your products and clients and orders as well as Controllers for accessing products, creating orders and more. And if your gateway works, then every command should be accessible over your API from the beginning, even before you have any HTML User Interface anywhere.

It’s a good reminder that an API gateway should be built so that you can make API calls not just over HTTP, but also internally, allowing you to load product information or save user data from anywhere. Perhaps you will have a button that makes an AJAX call for deleting a product? Or maybe a form that submits data to API call that adds a user? Or a View that loads product information over API internally and then populates the template with the product data? Every single functionality accessible through the API. This also allows you to do things like gracefully degrade your UI if the user does not have JavaScript as you can use the very same API to do AJAX actions as well as regular, no-script form submits.

Your visual and UI team could work independently at the same time, coming up with the user interface while you’re working on the functionality. And once that is done – once the software itself works – then you can start working on the following:

• Views - essentially what is returned to the browser, Views themselves can make API calls and can include the UI logic, error messages and more
• Implementation - navigation logic and integrating API controller calls within your Views

If you step back for a moment, then it is easy to see that what this API-centric development does is that it makes you entirely independent from your User Interface. It’s not just loose: it really is 100% independent. You can do everything through the API and this also means that you can implement any kind of user interface and environment: be it web, desktop software or mobile client.

This also makes testing – the bane of web developers due to multi-layered nature of web – far easier: you can test the API separately and deploy updates and bugfixes to your core software independently from User Interfaces. This makes software easier to maintain.

Desktop programming has largely worked this way for many years, but web has not yet caught up. Today – when the ability to quickly create mobile views of web services and/or mobile applications is business critical to both startups and established companies – this has become more important than ever. So next time you start building the next Twitter or Facebook: consider the API-centric development. Platform-independence just might give you enough of an advantage over the competition in a crowded market.

If you are interested in learning more or developing API-centric software, then there are frameworks that encourage such principles. I myself am a developer of Wave Framework which was born out of my passion for API’s and this principle is front and center in Wave Framework. So if you want to get up to speed quickly, then I suggest you look at the tutorials here and here.

6 Responses to “What you should know about API-centric web development”