Issue 23

How to go beyond APIs

Alpar Torok
Functional arhitect
@Hewlett Packard


If you don"t have APIs you don"t exist.

Well, to be fair, it would be more correct to say that without APIs you don"t exist in the cloud, but then again, can you exist outside the cloud nowadays? You must be thinking: nice compilation of buzzwords to start an article. Thank you! I hope the rest of the article will be equally compelling or less repulsive, depending on your taste for buzzwords.

Jokes aside, would you invest in a start-up that ignores the cloud and doesn"t have APIs? I know I wouldn"t. Software giants agree.

I also have to admit, I didn"t came up with the idea. I first heard it from Mac Devine, CTO of Cloud Services at IBM. He stood in front of an audience at the CloudOpen conference last year, talking about how to create a cloud-first company, and he was constantly making this point. If you don"t have APIs, others cannot consume data from you and cannot interact with you; it"s as if you don"t exist.

We also hear a lot about the new style of IT, and the power of developers. It"s a great time to be a developer, really. All this decision power is shifting, and developers get to have much more to say in the technology that gets used. It has gone so far, that it"s even infecting enterprise environments now. Some organizations have already taken this to extreme heights allowing developers to make changes and push them to production many times a day as they please.

What does that really mean? It"s actually really simple. You have to have good APIs. Really good APIs. The kind of APIs that others just can"t resist using. Of course, it helps if your service is valuable as well, but no matter how valuable it is, how accurate and reliable, if the API is hard to develop against, the developers with all the decision power will decide not to use it, or worse, will not even notice it. Are you scared yet? You should be. That lengthy documentation you spend so much time writing and maintaining will not help. Developers are notoriously lazy beings, to the extent that they consider it their virtue. That"s just another example of their powers. They will not read all your documentation, in fact they are likely to read the first paragraph at most, or just the headings, and expect that they can try it out right away, and understand it right away. And if they can"t, they will move on, because they are brilliant, experienced, empowered developers and if they can"t understand your API in five minutes, you are doing something wrong. And you know what? They"re right! Why shouldn"t it be like that? After all, you are competing for their attention with other providers.

APIs are by no means new. They have been around from the early 2000s, and even before that, if you consider not only web APIs.

Do you really think of anything other than REST when you think of APIs? Not a lot of people do any more. And the reason is that these were disruptive. Their simplicity won developers over. Everyone started using them, and selecting them over more complex alternatives. Wouldn"t it be nice if you could keep an edge, and anticipate the "next REST"?

More than an API: noAPI

It"s really catchy to innovate simply by prefixing a technology with "no". Is SQL a technology of the past? NoSQL to the rescue! It"s still like SQL, but different. So, why not noAPI?

Why not take APIs with their best features, but make it even easier to consume. Offer something that still makes it possible to manipulate and consume data and services, but is much easier for a developer to pick up. It"s not an API, it"s a noAPI.

Most of the time we no longer care about the specifics of the API; you don"t implement everything. We have language bindings. That"s an improvement, but is it enough? Everybody prefers to use them, they make sense, but at the end of the day language bindings are no much more than code reuse. Code reuse is great, but for ease of use, we can do better. The solution actually exists, and has existed for some time now; in fact you might already know it and used it without thinking about it.

Domain Specific Languages (DSL) are a great fit for this. They are considered to be a form of API in the traditional sense. DSL is a term that we use to describe a programming language designed with a specific problem in mind, as opposed to the general purpose programming languages we are used to. Its aim is to closely resemble the domain, making it simpler to think about and solve problems in that domain. Regular expressions are a domain specific language. We use them because it"s much easier than to implement the same functionality in some general purpose language. The more complex the pattern matching that needs to be done, the easier it becomes not to implement something custom. Because the language is close to the domain, it"s easy to use.

Let"s consider an example of offering a DSL instead of an API. Suppose we want to spin up a VM in a virtual environment. Just a bare VM, no templates, no OS install. The implementation for that could look like this:

    // [...]
    backingFile = new VMDiskBackingFile("/path/to/some/file/in/data/store")
    disk = new Disk(backingFile)
    vm = new VirtualMachine()
    vm  = VMService.getVM(vm.getName())
    // [...]

Some observations are in order. First, you might say that the provided API that we are using could be designed better. It most certainly can be improved. The reality however is that it"s common to see APIs like these and it"s not easy to improve them, while keeping the modular fast and generic.

Second, there are a lot of things for the developer to remember. Create the file before the disk and the disk before the VM. Oh and I forgot to mention, you need to get information about the VM back before you can power it on. I don"t trust myself to remember all these, so what can we do?

Consider this:

    vm {
        disk :  2.GB, backigFile "/path/to/some/file/in/data/store" { thinProvisioned },
        ram: 2.GB,
        power: on

Suppose you have multiple providers for your virtual infrastructure: the first one with the API in the first example; the second provider, with the DSL in the second one. Which one would you prefer?

Did you note the most important difference? With a DSL the developer doesn"t have to focus on the "how", only on the "what". That is a great relief; it freezes up the mind, and allows it to focus much better. It"s as if it"s reading your mind.

If you think it"s a lot of effort, and isn"t worth the effort, stay tuned for the third and final part of the article. It"s easier than you think.

Modern times, modern tools, quick implementations

Implementing a DSL might seem intimidating at first, so let"s briefly look at a simple way to implement it.

The JVM is home for many programming languages besides Java. Some argue that it"s even more important than the language itself. Groovy is one of these languages. It"s a dynamic scripting language with Java compatible syntax, called so probably only because JavaScript was taken. It"s low learning curve, most Java code is Groovy compatible, but not all Groovy code is Java compatible. And that"s where it gets weird. It can be so different that Java programmers will not even recognize it. In fact it can be so exotic, that it"s even hard to recognize that it"s Groovy.

In all fairness, Groovy is a terrible programming language for most things. It will let you shoot yourself in one foot, and reload for the other. It is however really good for implementing DSLs. They say on their website that they support DSLs, but it"s almost like the whole language was built for this sole purpose.

The good thing is that it integrates seamlessly with Java, so you can always implement part of what you want in Java if you want to, and use Groovy only for the DSL.

The scope of the Groovy meta programming model is beyond the scope of this article. It does have a learning curve, but it"s not excessively difficult, once one gets a hold of it. The good part is that it"s productive to work with; it does most of the work, so the learning curve pays off.

An added bonus is that the DSL becomes a subset of Groovy. What this means is that you can always mix Groovy in the DSL should you want to. You get data and control structures in the DSL for free. There are some great projects out there that implement DSLs with Groovy. One of my favorites is Gradle, which implements a built DSL. It"s fairly complex but a very good example for an implementation.

At a high level, the DSL is used to create a model of the domain in the initial configuration phase when the DSL is executed. Then the domain specific work is executed only after the model is complete. This allows the execution to reason about what needs to be done, knowing everything that needs to be done. In the earlier example, this would mean that the service knows the complete layout and specifics of the VM before it starts to be created.

There are a lot of other great and fast ways to implement DSLs. Most dynamic programming languages can be used to some extent.

It"s no longer necessary to start implementing a DSL by implementing a parser.

So next time an API is needed, will you consider noAPI?




  • Accenture
  • BT Code Crafters
  • Accesa
  • Bosch
  • Betfair
  • MHP
  • BoatyardX
  • .msg systems
  • Yardi
  • P3 group
  • Ing Hubs
  • Colors in projects