I am a programmer and architect (the kind that writes code) with a focus on testing and open source; I maintain the PHPUnit_Selenium project. I believe programming is one of the hardest and most beautiful jobs in the world. Giorgio is a DZone MVB and is not an employee of DZone and has posted 638 posts at DZone. You can read more from them at their website. View Full User Profile

Why everyone is talking about APIs

04.23.2012
| 9478 views |
  • submit to reddit
This article tries to answer a question that can easily be asked nowadays: why everyone is obsessed with APIs and how to create them?

Client and server

Ten years ago, the web server's job was to construct HTML pages and serve a dumb presentation layer to che client; JavaScript role was to reimplement the <blink> tag in a cross-browser way.

Now that we have the possibility of executing a reliable Turing machine in the browser and to perform Ajax calls, it has become a real possibility to move more and more responsibilities on it, and to JavaScript code.

The extreme end of this spectrum consists of one-page applications which never reload but only update parts of the window via XMLHttpRequest. The conversation with with the server is not a series of full HTML pages to load but a set of smalller requests:

POST /users
GET /users/1 #following the redirect
PUT /users/1/enabled

all of which return not an  HTML representation, but a JSON or XML one.

I listened to a talk by Gabriele Lana in Milan last week where he described how adopting an HTTP-based protocol is natural for separating business logic (exposed by the server) and presentation (executed by the client on JavaScript). Even when you should serve just HTML pages, the API forces a separation of the two layers and let the business or front end server change independently their implementation, language and machine configuration.

New possibilities

Apart from rewriting your front end in Flex or your business logic in Scala due to the clear boundary, there are several possibilities which an HTTP (I won't dare call it REST) opens up:

  • new front ends can be created: mobile versions of a web application and mobile native applications are the first that come to mind. The business logic remains shared while the front ends are created a new for each kind of UI.
  • integrating other applications is not performed by sharing a database but by accessing a stricter API that segregate a few actions available to the integrator instead of exposing every table, letting the API-based application evolve independently as much as possible and avoiding surprises when the data model changes.
  • there is the possible business advantage of providing access to the APIs to other applications of yours.
  • If your application does something interesting, you can also provide access to other people (even for a fee). This is particularly true if the application works over something more difficult to integrate, like such as devices normally disconnected from the Internet like sensors.
  • The idea of Open data is to provide a read only API to access government data, which would by themselves sit on an hard disk if exposes just through the original public website.

The challenges

Browsers are not capable to perform PUT ot DELETE requests, leaving only GET and POST available for accessing an API. This issue leads to use a fictitious parameter added to the URL to tell the server that the current overloaded POST request should be treated as a different method:

POST /users/1/enabled?_method=put

POST is used over GET to maintain the semantics of a non-safe method that modifies the application state. It is unclear whether HTML 5 will mandate the support for PUT and DELETE requests in forms.

Another issues is latency, the round trip time necessary for satisfying a minimal HTTP request; there have been experiments like SPDY to try to lower latency, but initiating many different Ajax requests to compose the pieces of a page on the client may put a strain on the channel; browsers commonly peform only 6 parallel requests for domain at a time. Fortunately you can at least cache every piece of the page independently without the need for an HTTP accelerator like Varnish.

History

The last potential problem is with history management, or how not to break the back button: by default, completed Ajax requests do not change the URL displayed in the location bar, meaning that it is impossible to reach the previous state of a page with it.

In the past, hashbangs like #!stateName have been added to the current location to simultaneously avoiding a redirect and provide a new placeholder URL. Now HTML 5 History provides (in more and more browsers) an API for modifying the URL in a real one, letting you change /users in /users/1 without reloading the page.

It's even a degradable enhancement, since you can provide real links to the new locations (that will work on older browsers) and intercept their click event to load fragments with Ajax, updating the history via JavaScript.

Conclusions

It is possible to use a JSON or XML API as the HTTP server's end point, given the current state of browser functionalities; moreover, the universal flavor of HTTP will make the same business logic accessible from everywhere. Even internal parts of your application (Bounded Context) can benefit from being extracted and integrated with an API, which will let them evolve independently in technology, deployment options (how many servers?) and even language.

Published at DZone with permission of Giorgio Sironi, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)