Contract-first development of RESTful services


When I was a young backend developer SOA was hot. Every enterprise application consists of web services exchanging XML messages over SOAP. The functionality offered by these web services were described in a WSDL file (Web Services Description Language). This WSDL is the contract both parties use to communicate with each other. It specifies how the service can be called, what parameters it expects, and what data structures it returns. Normally there were two ways we would work with WSDL’s.

Contract last

We just started coding the functionality in Java. With the frameworks we used we just add some annotations or comply to a certain convention and the web service was published. From the code a WSDL could be generated and threw over the fence to the other party, good luck with it.

Contract first

When working contract first the WSDL is created beforehand. And at the moment the WSDL got finished we started implementing, mostly by starting with generating Java code from the WSDL.

I remember we could always have fiery discussions in the team whether to work contract first or contract last, but in the end we always had a contract. When we delivered the web services, the WSDL was indisputable the single source of truth, everyone was happy. In the past everything was better, right?


Fast-forward a few years and all new services should be RESTful with JSON. Instead of those verbose XML files we transfer lightweight JSON files. When developing my first REST endpoints I loved the conciseness and flexibility, but deep down I also missed the firmness I got used to when working with WSDL’s.

Some WSDL-like tooling for REST arose in the form of WADL (Web Application Description Language). This describes the REST endpoints, parameters, data structures in XML quite similar to WSDL. After working with that flexible and concise JSON, putting a lot of effort to create a WADL in XML just didn’t felt right. So I took a look at it, but it never occurred to me to really use this. Until today I never came across a WADL in the wild wild REST world.


Around 2011 Swagger came around. Now we could add the Swagger library to our project that provides some annotations. Based on these annotations documentation about the REST interface could be generated like this:

With minimal extra effort (adding some annotations) we’re almost at the point of contract last development of REST endpoints. In addition Swagger gives us an easy-to-use tool to test the REST endpoints. Also useful for other parties who write software to integrate with this interface. But still, this is no contract. We have useful documentation of the REST interface for humans, but it still lacks a format that is indisputable, unambiguously, and preferably machine readable.


So this is where the OpenAPI Specification (OAS) kicks in. Originally developed by Swagger and meanwhile donated to the Open API Initiative. With the OpenAPI Specification we can create a single interface file as contract in JSON or YAML. From this interface file documentation of methods, parameters and models can be generated. Also REST clients and servers for most major languages/frameworks can be generated.

Getting started

The easiest way to get in touch with OpenAPI is by opening the online editor at: By default this loads the pet store API which is a comprehensible sample project. The specification (in YAML) can be edited in the left pane of the editor. The righthand side contains the documentation and is refreshed on the fly. Seeing your changes and their effects being applied in real time is a great way of developing your contract!

When working on your private project you may not want to edit your specification in the public editor. This same editor can simply be installed locally via NPM. To get started I created this Git repo that provides a decent starting point. If you have any questions, file a new issue in Github or ask it here below in the comments.

Final thought

I gave a brief starting point and now it’s up to you to play around and use it for real. Most of us programmers are a lazy bunch and we prefer to automate as much as possible. Today I will cheer on this habit and tell you to “never ever write your REST interface code by hand”. Let it be generated based on an indisputable contract!