What you should know about API-centric web development and design

September 17, 2013 at 20:11

API-centric design

API-centric design

This article was originally publised in 2012. It has been updated with new information about advancements in API-centric design in 2013.

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. A stateless protocol is one where there exists a single request that has a single set response, independent of every other request sent to the system. But modern web applications are often anything but stateless and consist of layers upon layers of session handling and asynchronous requests, where users can log in and their functionality is dependent upon dozens of checks before a page is returned to their web browser. In order to manage this problem a little better, we have to take discover – or rediscover – something that has existed in desktop software development for a dozen years: API-centric development and design.

An API acronym means Application Programming Interface. An API is a set of rules, almost a programming language and logic in its own right, that is defined as a way to use functionality of a software. It is likely that you have 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. An API would allow you to create users, log users in, view product information, generate pictures, validate data and any other function that you can think of that your software should be able to do. Problem is that this type of logic is not decoupled – independent from one another – in web development.

An average website or infosystem that your web development team has created for you depends on page logic. Every page on your website carries a specific set of functionality. On some single web page URL you take a product template, populate this product template with product data from database, authenticate a logged in client and fetch specific price or discount for that client on that product page. This is a large amount of functionality just to be carried upon a single page.

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, such as a partner requiring to synchronize data with you or another website requiring access to some information that your system is storing. This is a situation where your ‘website-like’ system, where every data is shown on your HTML pages over website URL’s, is suddenly not good enough. 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 from your website or infosystem, as if API should be an additional component of your software. But an API should be your software – everything else is just an interface that interacts with the API.

In API-centric design you would decouple each of those components and you can use and reuse these components and functionality across your entire web page. Each of these little things I mentioned could then be used whenever across your entire system and not only used, but also developed largely independently from one another by developers in your development team. API-centric development is nothing new for software development in general, but this type of thinking is new for web development. API is critical for well architectured modern web software, be it even just a simple website and it does not have to just be something that big and successful companies do. An API-centric design can not only make your software more usable and dynamic, but it can also be maintained better and reduce your development costs in both time and money.

So how to approach this problem differently?

First step for a solution to this would be another acronym: MVC. MVC means Model-View-Controller, which is system architecture design where you separate your components based on their primary duty. A model is meant for representation of a data object that is loaded from or stored to database, a View is meant to simply be a template and template logic that represents your user interface (often to show details about a Model) and a Controller is meant to validate and execute different functionality in your software, such as authentication and fetching certain Models as a response to a request.

Not only don’t most websites use any kind of MVC at all, but majority of those that do implement the whole Model-View-Controller architecture wrong.

In an MVC pattern the Views should consist of both User Interface components themselves and the UI logic, but in a lot of web development out there the Views are only that in name as websites implement Views as an entire ‘page’ HTML, as a template or a procedural script, that is populated throughout with higher logic that has no business in Views – things like database requests serve no purpose within actual Views.  Controllers are often just a vague entity that tries to do anything from AJAX to event handling to form submits and are often tightly coupled with Views. Models are often implemented correctly, but reality is that a lot of web services don’t implement Models at all.

This means that in order to even get to the idea of developing a good API, you must first implement the MVC architecture well, because a good API design works well only on architecture that is decoupled, where components are separated from one another and every component only handles, in best case scenario, a single task. On a good architecture API’s enable a way to use software without 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.

What are the steps I should keep in mind?

Every web service – even a website – can also be programmed by developing it by developing your 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 – your website HTML – at all. Suddenly your functionality is not tied to website URL logic and you don’t need to ask anymore what functionality you have to develop for what ‘page’. Your software functionalities are still the same and it still needs to do things A, B and C, but suddenly your functionality has nothing directly to do with your beautiful website. This type of thinking helps you to iron out most of the MVC-from-desktop-to-web kinks that are often caused by the simple fact that the UI is getting in the way.

Once you have your functionality listed and you know what your software needs to do, you can start focusing on how to plan the software components for it. The entire functionality of a web service should focus all of its development early on to develop only 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 or validating users login data.
  • 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.

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 as your Controllers that implement your Models. 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 set up.

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 should be 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 is very important in modern development, as web development is not just for web browsers anymore. You need to cover mobile web and make your software easily usable over mobile applications for iOS, Android and more.

This also makes testing – the bane of web developers due to multi-layered nature of web – far easier as 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, you should consider an 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.

Tags: , , , ,

9 Responses to “What you should know about API-centric web development and design”

  • emmanuel Nyachoke says:

    I talk to my emploler about the possibility of use adapting a software approach of create once use from anyware and we were think of creating our own internal micro-framework but I have looked at wave and it fits does all we wanted thank for the post.

  • Kristo Vaher says:

    I am glad to hear. You would not be the first one, there are a number of companies and independent developers using Wave so far and I can assist them personally. If you have any questions I do offer an as-soon-as-possible support through my e-mail at kristo@waher.net so if you run into problems I’ll help.

  • Very informative. thanks.

  • Russ says:

    Thanks for this post – it prompted me to download wave, and I am quite impressed. It is nice and easy to get started quickly (unlike some other frameworks out there!). The only thing that worries me at the moment is that it is not possible to pass parameters to constructors (or rather, __initialize, as __construct is final) in classes that extend WWW_Factory. This make dependency injection rather more difficult.

  • Kristo says:

    Hi Russ!

    You bring out really valid points.

    Currently the Factory and methods that dynamically return MVC objects (the getModel(), getController() and getView()) can have parameters passed to them, but these are used to execute various functions on demand. This is something that I’ve wanted to deprecate for a long time, since I’ve never used this functionality (I either use an API or return one of the methods and then use it).

    By the way, I intend to release 3.8.0 really soon, which will very greatly increase the flexibility of Wave Framework. It will be possible to extend MVC objects (one can extend another and even Factory itself can be extended (you can have a WWW_controller_me extends WWW_Factory_me (which then can extend WWW_Factory)).

    Thank you for giving me the incentive to make these little changes and implement them in Wave.

Leave a Reply

You must be logged in to post a comment.