How far should API definition languages go?

I had the pleasure of writing an article for Nordic APIs on Web API definition languages.

If you're into the world of Web APIs, you've probably heard of formats like Swagger, RAML or API Blueprint. They allow developers to define the contract of the API, with its endpoints, its resources, its representations, allowed methods, the kind of payloads it understands, the status codes returned, and more.

With the contract of your Web API, you can generate code for your backend implementation or client kits, documentation for publishing the details of your API for your API consumers. This contract becomes a key element of your API strategy: a contract between the frontend team and backend team to be sure to work on the same ground, between your tech team implementing the public API of your company and all the API consumers that will interact with it.

But API definition languages don't necessarily denote all the fineness of your API, in particular its business rules, or how to check that an implementation conforms to a contract or if the implementation follows the style guides of your company, what tests could exhibit the behavior of the API, and more. So the questions I asked myself was how far should API definition languages go!

A web API for each API consumer?

At our disposal, we have so many ways to interact with an API: from a mobile on iOS or Android, from a web application, or from other services or microservices. And all of them have different needs: one wants only a shallow overview of the data, while the other desires a detailed view of a certain resource and all its sub-resources. It's becoming difficult to design an API that caters to the needs of those varied consumers.

So what can we do? There's a trend around providing different API facades for each consumer, as Netflix does with its experience and ephemeral APIs, or how Sam Newman described it in its Backends for Frontends pattern. But such an approach increases the maintenance burden and complexity, and might only really make sense for big enough teams. 

Other approaches exist for customizing payloads for different consumers, without really providing as many derived API facades as you have API consumers. You can take advantage of the Prefer header, fields filtering, custom Mime media types, hypermedia, or Facebook's GraphQL approach.

I've written an article for InfoQ that dives into this topic, and covers all those subjects: "One API, many facades".

Groovy default params to avoid one-argument methods being called without params

Recently, I saw an interesting tweet, mentioning a JavaScript trick using default parameters to make a parameter mandatory. 


In a language like Apache Groovy, when statically compiled, you'd get a compilation error if you forgot a parameter, because the signature couldn't be found by the compiler. In dynamic mode, you'd get a runtime error though, with a MissingMethodException (and the error message should give you a hint as to which method you should actually call instead). 

But there's a particular case of the Groovy method dispatch that's a bit special (and actually something we might be removing at some point in a breaking version of the language, but it's been there since 1.0). When you have single-argument methods, you're allowed to call those methods without passing a parameter! And the parameter is filled simply with null. So you might have made a mistake in your code, forgetting to pass an actual parameter value, but you'd get neither a compilation error nor a runtime exception, but a null value. 

So I thought about that JavaScript trick, and adapted to this situation, to ensure that you can't call a one-argument method without an argument.

String up(String s) {
    s?.toUpperCase()
}
assert up('groovy') == 'GROOVY'
// a strange aspect of Groovy is that 
// you can call a one-argument method without passing any actual argument
// as if you were passing null, as in up(null)
assert up() == null
// let's use the JavaScript trick with mandatory default params:
// https://twitter.com/djsmith42/status/679018096334675968
String up2(String s = mandatory('s')) {
    s?.toUpperCase()
}
void mandatory(String paramName) {
    throw new Exception("Please provide an actual value for '$paramName'")
}
assert up2('groovy') == 'GROOVY'
try {
    up2()
} catch(emAll) {
    assert emAll.message == "Please provide an actual value for 's'"
}
// another approach with using a closure call as default value
String up3(String s = { -> throw new Exception("Please provide an actual value for 's'") }() ) {
    s?.toUpperCase()
}
assert up3('groovy') == 'GROOVY'
try {
    up3()
} catch(emAll) {
    assert emAll.message == "Please provide an actual value for 's'"
}
I've also pushed that example on the Groovy Web Console, if you wanna play with it.

Groovy Weekly #77

It’s literally the eve of SpringOne2GX, in Washington DC! I’m flying tomorrow, for 9+ hours above the Atlantic, to gather with the cool kids of the Groovy ecosystem. I’m impatient to see some of my fellow readers and Groovy users around there.


And let me wish the Griffon framework and its team a Groovy birthday!

Releases

Articles

Screencasts

Interviews

  • An interview by JaxEnter of Dierk König in German, where he says that Groovy is a pioneer language where innovative changes help shape the future of Java and other languages

Mailing-list posts

Tweets

News

Jobs

Books

Events

Groovy Weekly #76

Is it really already September? Time flies so fast in the Groovy ecosystem, and although the northern hemisphere was taking some Summer vacation breaks (at least that’s what I did!) there was quite a bit of interesting content published!


Regarding events, after successful and busy Greach, GR8Conf US/EU conferences, we’re getting ready for September’s SpringOne2GX in Washington! There’s still time to register and join the Groovy ecosystem affictionados! And I’m really eager to seeing you there.


The Call for Papers for Grails India and Groovy Grails eXchange London are also open, for those who wish to submit presentations.


If you’re using Gradle for build automation, check out all the videos of the presentations of the recent Gradle Summit which should all be available online.


Happy 3rd birthday to GrooScript!

Congrats to the Griffon team for the 2.4 release and Ratpack for its RC before 1.0!


And check out the updated books from MrHaki on Groovy, Grails and Gradle, and Duncan Dickinson’s updated Groovy 2 tutorial on LeanPub.

Releases

Articles

Presentations

Mailing-list posts

Tweets

News

Jobs

Code snippets

Books

Podcasts

Events

 
© 2012 Guillaume Laforge | The views and opinions expressed here are mine and don't reflect the ones from my employer.