While reading the documentation of popular web APIs, I discovered that they often impose constraints on multiple parameters of an API request. Web API specifications languages, on the other hand, have little to no support for expressing those kinds of constraints.

In this talk, I’ll show that these inter-parameter constraints are very common, even in well-known web APIs such as Google Maps, YouTube, Facebook and Twitter. Although these patterns pop up naturally in web APIs, they are completely missing from specifications languages.

The inability to write down inter-parameter constraints in machine-readable specifications has consequences for their tooling eco-systems as well. Inter-parameter constraints are missing in generated textual documentation, editors and generated code. On top of that, the API providers themselves are not helping either! Every API provider responds differently to requests that do not satisfy their inter-parameter constraints (and not always with an error message!), which causes a lot of bugs to go unnoticed.

At the end of my talk I show how web API specification languages can be adapted to support inter-parameter constraints, and which benefits this has for the tooling eco-system around specification languages.