Inter parameter dependencies

Table of contents

1. What is an inter parameter dependency?
2. IDL: a language to specify inter parameter dependencies
3. An OpenAPI extension: x-dependencies

What is an inter parameter dependency?

There are many APIs which restrict the use of two or more parameters combined in a request. That's what we call inter parameter dependencies. We will take the YouTube Data API as an example. The GET operation of the /search path describes a considerable amount of inter parameter dependencies. For example, you can only specify one of the following parameters: forContentOwner, forDeveloper, forMine or relatedToVideoId, or if the location parameter is set, you must specify the locationRadius one. If the request does not comply with the restrictions, the API will return a bad request status.

IDL: a language to specify inter parameter dependencies

Currently the OpenAPI specification does not support parameter dependencies and mutually exclusive parameters, as stated in the OpenAPI specification documentation. This is the option OpenAPI offers:

What you can do is document the restrictions in the parameter description and define the logic in the 400 Bad Request response.

It is infeasible to infer the inter parameter dependencies from a formal description in many cases, so it is necessary to design a language which describes those dependencies with a machine-readable definition.

RESTest uses IDL, a language that allows the inter parameter dependencies to be defined in a machine-readable way, so it can be interpreted by an algorithm.

WIP

An OpenAPI extension: x-dependencies

WIP