Introduction

I have been doing a lot of thinking recently about adding REST (Representational State Transfer) API support to the Alpha Framework, which is presently on the roadmap but unscheduled. In this article, I will attempt to capture my thought processes on how this will work, and how it will be introduced into the framework with the minimum of impact.

My design goals are as follows:

1. The support of REST-style requests and responses will be implemented at the framework level, no other coding should be required on behalf of the user of Alpha to implement a fully-functional REST server.
2. The code impact on Alpha should be minimal. Ideally, I want to be able to inject in support for different object renderers via a factory, at runtime.
3. The default content type returned will still be HTML. Initially I will also add XML, plus an extensible framework that will support the addition of other formats like JSON.

Handling requests

The controllers in Alpha presently have support for doGET and doPOST methods, which are a requirement of the AlphaControllerInterface. The methods are used to implement the code which will handle GET and POST requests respectively, but typically in a REST based solution you will also handle these additional request types (or verbs):

• PUT - some REST implementations strictly use POST for creating new objects, and PUT for updating existing objects. The key difference between POST and PUT is that PUT is idempotent, meaning that a client can safely resend the same PUT request multiple times and always be sure that the object on the server will remain in the same state, whereas this is not the case with POST (hence you browser warning you when you want to resend a POST request). Given that every update request of a business object in Alpha will result in a state change (version number incremented, last updated timestamp changed et.), I do not think that a doPUT method in the framework is a good idea in terms of adherence to the HTTP specifications, hence I will stick with doPOST for object creation and edition.
• DELETE - as the name implies, this verb is used for deleting objects (or resources in HTTP parlance). Presently, deletion is handled in Alpha by the doPOST method, due to the limitation in HTML forms that they only support GET and POST, however it makes sense to include a proper doDELETE method to handle all delete operations, both from a HTTP DELETE request from a REST client and a POST request from a web browser (the doPOST will have to check for a delete button press when handling web forms, then invoke doDELETE acordingly).
• HEAD - the HEAD verb behaves in a similar fashion to the GET verb, with the key difference being that HEAD does not return a body: it only returns the HTTP headers. HEAD is very useful if you want to check if a URL is valid (check for a 200 response as opposed to a 404), while you are not concerned about the body of the response so choose to not have it returned by the server, which saves on bandwidth. Another example is when you want to check the type and size of a file before you download it: a HEAD request will return the Content-Type and Content-Length headers in its response, but crucially it will not include the binary content of the file in the body of the response, allowing a REST client to inspect a file resource before committing to downloading it. A doHEAD method will be therefore will be included in the Alpha Framework.

Handling responses

Presently the Alpha Framework has only one response format: HTML. When I designed the framework, I played with the concept of a viewMode property on each view class which would control the output format used in the response, but I removed this before the 1.0 release of Alpha because I felt that it just added complexity. Given that the REST API will now force this back into scope, I will need to address this requirement as cleanly as possible without impacting on the existing systems using Alpha 1.0.

At a high level, here are the following formats that I would like to target:

1. A standard web page (HTML5)
2. A mobile web page (also HTML5, but smaller dimensions)
3. A REST API response (XML)
4. A REST API response (JSON)

This is a lot of work, but my intention is to add the supporting framework first, then add the various output formats one at a time afterwards (with the existing HTML4 standard web pages being upgraded to HTML5 as the first priority, followed closely by the XML REST responses).

But how does the framework know the desired format to return to the client?

Well, there are two approaches here: have a different URL for the different response formats, or use the Accept header set in the request by the header. A lot of APIs are using the first approach, for example the Twitter API uses the concept of a file extension on the URL (even though no actual file is returned), using .json for JSON responses and .xml for XML responses. My understanding of REST however is that the aim is to have a single URL per resource, and for me using a file extension or other URL parameter violates this.

The Accept header seems like a neater approach to, which is often termed content negotiation. If the client wants the XML or JSON responses, it should set one of the following headers on its request:

Accept: application/xml Accept: application/json

To keep things simple, for all other Accept header values the HTML5 response will be returned. The default action will be to return the standard-sized HTML5 page (the return of the smaller sized mobile version is likely to depend on the result of some User-Agent string inspection on the server side).

Conclusion

Adding REST API support to an existing framework like Alpha will be challenging but rewarding. The ability to think of data in Alpha-based systems as business objects, which can be viewed in a number of different formats (HTML, RSS, Atom, PDF, Excel, and soon XML and JSON) is a core concept of the Alpha Framework. The business object, reflecting the real-world concern we wish to capture, should be abstracted from the concerns of how it will be represented to the user in terms of formats. REST API support goes a step further however, as it requires modification of the controller logic in Alpha to handle the different HTTP verbs, so it is a much bigger addition to the framework than, say, adding another object renderer.

You will notice in all of this that I have not mentioned SOAP. I have done a lot of work with SOAP over the years and there are some things that I like about it in comparison to REST, like the design-by-contract that a WSDL gives you. However, Alpha is squarely focused on the web application space, not the enterprise application space, and right now on the web REST is the dominant approach for public APIs, and with good reason: it makes better use of the HTTP protocol than SOAP does and HTTP is the backbone of the web.

---

Updated 2022 : note that the above post was originally published in 2011, but is left here for archival purposes. I have fixed some external links above.