In part I of this series we've talked about the most prominent use-cases for PaaS and I provided some reasons why I believe that the provisioning of APIs is one of them. In today's blog post we'll get a bit more technical and shed some light on how-to build apps that expose public APIs.
Setting the stage
Before we get started it sounds like a good idea to have a quick look about what Wikipedia has to say about APIs so that we have a common understanding of the term:
An application programming interface (API) is a specification intended to be used as an interface by software components to communicate with each other.
While I assume most of the readers are fairly familiar with the concept I considered it to be worthwhile to have a closer look at the definition again, because it helps us focus on some of the most vital aspects of it:
- APIs are an interface and as such are expected to be somewhat stable or at least backwards-compatible.
- APIs are used by other software components = consumers or clients. These components are build by developers.
The reason to explicitly mention this is to raise awareness about the fact that developing a good API is something not to take lightly. The intention to develop an API is to allow others to develop applications against it and as such the interface should cater to this need. You'd want to make it as easy and intuitive as possible, while at the same time making the API flexible enough to grow over time without enforcing developers to cope with incompatible changes. So, if you consider writing an API I'd recommend to spend some time designing it before releasing it to public - as once it's out there you may no longer change it at will (well, at least not without upsetting your consumers!)
Fortunately, there are lots of resources on the web providing excellent insight and best practices when it comes to API design. I recommend the content provided by the nice folks at Apigee [http://apigee.com/about/resources/] and especially their "Web API Design - Crafting Interfaces that Developers Love" eBook as a good starting point. You may also want to read about the experiences sufw shared about developing RESTful APIs from Scratch: Lessons Learnt (so far).
RESTful services
With the design aspects sorted out it's now time to look into the implementation details. So, what is the best way to develop an app that exposes its functionality as an easy-to-consume API? Well, it looks like the most popular approach these days is to use RESTful services. In contrast to other "web services" technologies it's not a standardized protocol (such as SOAP), but more of an architectural style using a mix of other standards.Some consider this as a drawback, others emphasize that exactly this lack of standardization makes it so flexible and easy to use.
Fact is, using the HTTP protocol and its verbs (read HTTP methods) helps to keep things lightweight and easy to implement and consume. Most browsers (incl. mobile ones) understand this protocol without any additional plugins or tools. Typically JSON (JavaScript Object Notation) is used as the data format, which is less verbose as XML and - again - is supported by most browsers out-of-the-box. Consequently, this combination seems to be a perfect match for modern application in times of web 2.0.
Java Servlets
Based on the above it sounds as RESTful services may be the best option for the provisioning of an API. Fortunately, it's quite easy to develop them with Java. Matter of fact, if we take a trip down memory lane we'll see that the Java Servlet API already supports (simple) means to communicate via HTTP and that the HTTPServlet provides functionality to implement all HTTP verbs. Some may doubt that a technology from 1997 is the appropriate solution to address modern (web) development needs, but it's not far off the truth. Matter of fact, I was skeptical at first too, yet after giving it some further thoughts I realized that, while the technology may be a bit out-dated, yet it has all the characteristics of a great API:
- it's lightweight
- it's robust and mature
- and it's flexible (read: easy to extend!)
We've seen plenty of great frameworks and libraries being built on top of Servlets. One of the most prominent ones being Struts, which became one of the most popular MVC frameworks of its time. So, for the last decade Servlets weren't used directly anymore, but served as the foundation for other frameworks and libraries. At the time, the server did most of the heavy-lifting and provided the whole enchilada in regards to multi-tier applications from database, to services up to the presentation layer. Nowadays, with the rise of smartphones and tables equipped with modern browsers we see a trend to let the client take care of the presentation and control flow of an app and the server is only providing the data via well-defined services. It has become state-of-the-art to shift the MVC pattern to the client, regardless of whether it's a web-based (e.g. HTML5) or native app.
JAX-RS: Java API for RESTful web services
Consequently, the type of frameworks built on top of the Servlet API have evolved addressing these needs. Not surprisingly there is a variety of frameworks that focus on supporting the development of RESTful services based on the JAX-RS API. In a recent blog postdagfinn.parnas already explained how-to use the JAX-RS reference implementation Jersey. In part III of this series we'll have a closer look on Apache CXF and develop a baseline project you can re-use as a starting point for your own applications.
PS: NO - you do not have to use Servlets directly - after all: it's soo last-century! :wink:
