Skip to Content

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 [] 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 @Sascha Wenniger 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! 😉

To report this post you need to login first.


You must be Logged on to comment or reply to a post.

  1. Sascha Wenninger

    Hi Mathias,

    nice one – especially the part about remembering to put some effort into design! Building a good API (which developers will want to use) is not simple and probably will take more than one attempt. Just because REST is billed as so much simpler than SOAP and its WS-* mess, doesn’t mean it’s also simpler to build. It means it’s simpler to use, (after all that’s what’s important). For example, the extensibility brought by JSON through its loose typing model and mustIgnore parsing conventions comes at the cost of more hand-coding and less “right click-generate web service” magic.

    Good to see Servlets making an appearance. The first SAP product I ever worked with was MII (then freshly-badged as xMII after SAP bought Lighthammer); that product heavily used Servlets which implemented an (almost RESTful) HTTP API to build AJAXy dashboards and web UIs, and it seems their architecture would still be as valid today from what I read above 🙂

    There is of course nothing wrong with mature technologies dating back to the last millennium if they have proven themselves in the wild. After all, RFC2616 which forms part of the RESTafarian holy scripture, was written in 1999!

    Thanks also for the shout-out, and definitely looking forward to Part 3! 🙂


    1. Matthias Steiner Post author

      Thanks for providing further insights to the topic Sascha.

      For example, the extensibility brought by JSON through its loose typing model and mustIgnore parsing conventions comes at the cost of more hand-coding and less “right click-generate web service” magic.


      As I tried to convey, there’s no silver bullet and every approach has its own pros & cons. Having done both: hand-crafting and “right-click magic” I have to say that from an end-to-end perspective the hand-crafting one seems to be the more productive one, which yields faster results and shorter innovation cycles. Especially if one is using the right tools. I’ve become a big fan of JAX-RS over the last couple of months as it makes exposing functionality quite simple – regardless if one is going for RS or WS.

      If given a choice between a black-box MDA-tool and a well-documented API – most developers (I know) would opt for the later. 😉 Just food for thoughts…

  2. Kumud Singh

    Hi Matthias,

    I have been seeing a lot of discussion regarding REST on twitter and finally I read your blog. I got a fair understanding and now would have to read all the related contents. Thanks. 🙂



    1. Matthias Steiner Post author

      Happy you found the post useful Kumud! I especially wrote it to make the transition from the high level part I to the very technical part III (coming shortly) easier for people who are just getting started with the topic.

      And you’re absolutely right, the more you learn, the more you realize what you don’t know – it’s a humbling, but rewarding experience though!

      In fact, that’s why I promote OpenSource software as well as using APIs instead of shiny MDA-tools. It’s because they make you understand the basics. Ultimately it makes you a better programmer and one that has mastered the tools….

      1. Sascha Wenninger

        Hmm, how do you quote from a reply? Anyways, you said

        “you’re absolutely right, the more you learn, the more you realize what you don’t know – it’s a humbling, but rewarding experience though!”

        and I couldn’t agree more. My absolutely most favourite uni course was “Advanced Topics in Operating Systems” because it drilled down through all of the layers to the bare metal, one layer or two every week: application code > OS libraries > file system > disk driver > bus > DMA memory access > disk controller. Fascinating stuff, and really made you get an appreciation of all of the abstraction layers with even something as basic as opening a file in an app.

        Anyhow, this got me thinking about probably one of the most profound articles I’ve (re)read in a long long time. Full credit to Alisdair Templeton for introducing me to the Law of Leaky Abstractions; the article is well worth 20 minutes and I highly recommend it:

        To me, this speak so much of the importance of understanding the code and programs you’re writing, rather than just knowing how to drive the tools and frameworks. Kumud Singh, I’m sure you’ll find this interesting too 🙂

        Turning off my propeller now, and having a beer 🙂


        1. John Patterson

          Hi Sascha

          The Law of Leaky Abstractions is one of those articles I re-read constantly, thanks for bringing it up, more relevant today than ever, everyday we see more and more 5 minute abs commercials.

          “even as we have higher and higher level programming tools with better and better abstractions, becoming a proficient programmer is getting harder and harder.”

          “learn how to do it manually first, then use the wizzy tool to save time”

          I completely agree about the “importance of understanding the code and programs you’re writing”, I think in the case of API’s it is very important also to understand how others will use/misuse it outside of the use cases you wrote it for.


          John P


Leave a Reply