Inter parameter dependencies

Table of contents

1. What are inter-parameter dependencies?
2. IDL: describing inter-parameter dependencies
3. IDL4OAS: including dependencies in an OAS document

What are inter-parameter dependencies?

Inter-parameter dependencies are constraints that restrict the way in which two or more input parameters can be combined to form valid calls to some API operation. For example, the documentation of the search operation of the YouTube API states that, when using the videoDefinition parameter, the type parameter must be set to video, otherwise a 400 status code ("bad request") is returned:

IDL: describing inter-parameter dependencies

Automatically generating test cases without managing inter-parameter dependencies is hardly possible in practice. To approach this issue, you can formally specify the inter-parameter dependencies present in the API using Inter-parameter Dependency Language (IDL), a DSL designed to support all types of inter-parameter dependencies found in practice. Then, these dependencies will be taken into account when generating test cases.

Following are some examples of dependencies described in IDL. To know more, visit the IDL repository and the sample IDL specifications.

IF videoDefinition THEN type=='video';                      // Requires
Or(query, type);                                            // Or
ZeroOrOne(radius, rankby=='distance');                      // ZeroOrOne
AllOrNone(location, radius);                                // AllOrNone
OnlyOne(amount_off, percent_off);                           // OnlyOne
publishedAfter >= publishedBefore;                          // Relational
limit + offset <= 1000;                                     // Arithmetic
IF intent=='browse' THEN OnlyOne(ll AND radius, sw AND ne); // Complex

IDL4OAS: including dependencies in an OAS document

You can include the definition of the IDL dependencies within an OAS document using the IDL4OAS extension, like this:

  /example/path:
    get:
      parameters:
        - name: "p1"
          in: "query"
          required: false
          type: "boolean"
        - name: "p2"
          in: "query"
          required: false
          type: "string"
      x-dependencies:
        - IF p2=='example string' THEN p1;
        - Or(p1, p2)
      responses:
        default:
          description: "Default"