Inter-parameter dependencies in REST APIs
Did you know that 4 out of every 5 REST APIs contain inter-parameter dependencies?
Summary: REST APIs often include dependency constraints that restrict how two or more parameters can be combined to form valid API calls. These inter-parameter dependencies make it difficult to automatically interact with the services, since API specification languages offer little or no support for them. We carried out a study on 40 industrial APIs and found that 85% of them contain inter-parameter dependencies. More importantly, we classified all the dependencies found (over 600) into seven patterns, serving as the basis for future proposals for modeling and analyzing inter-parameter dependencies automatically.
So… what’s an inter-parameter dependency?
An inter-parameter dependency is a constraint between two or more input parameters of an API that must be satisfied to form a valid API call.
As an example, the YouTube API provides a search operation to look for videos, channels, playlists, etc. This operations accepts 31 different input parameters (e.g., channelId and location), and it contains 16 inter-parameter dependencies (that’s a lot!). Next you see an example:
As you can see, using the videoDimension parameter makes it required to set the type parameter to 'video', otherwise the API returns a client error (400 status code). That’s an inter-parameter dependency.
Can inter-parameter dependencies be described using API specification languages?
No, they are not currently supported by any API specification language. There are several alternatives when it comes to describing a REST API such as OAS, RAML and Blueprint, but none of them allows to formally specify inter-parameter dependencies. This drastically hinders automation. Any tool that leverages the API specification such as source code generators and testing frameworks (for example, those provided in the Swagger tool suite) cannot take advantage of these dependencies, since they are not formally described anywhere. Cedric Warny put it nicely:
How common are inter-parameter dependencies?
We recently carried out a study on 40 industrial APIs and 2,557 operations [1], including YouTube, Foursquare or GitHub, among others, and found that these dependencies are present in 85% of them. Also, they appear in all types of operations (GET, POST, etc.) and across all types of parameters (query, headers, etc.). As the main outcome of our study, we managed to classify all dependencies found (over 600!) into seven well-defined patterns, presented below.
Catalogue of inter-parameter dependencies
1. Requires
The Requires dependency is the simplest pattern. If a parameter is used (or it has a certain value), then another parameter must be used too (or be set to a certain value). Therefore, the YouTube dependency shown above is a Requires dependency.
2. Or
Out of two or more parameters, at least one must be used. For example, in the Flickr API, when setting the information of a photo, the documentation states: “At least one of description or title must be set”.
3. OnlyOne
Out of two or more parameters, one, and only one of them must be used. As an example, in the Twilio API, when sending an SMS, only one of From or MessagingServiceSid must be used: “You must also include either the From parameter or MessagingServiceSid parameter”.
4. AllOrNone
Out of two or more parameters, either all of them are used, or none of them. An instance of this dependency can be found in the GitHub API, between the parameters subject_id and subject_type of the operation GET /users/{username}/hovercard, as shown in the screenshot below:
5. ZeroOrOne
Out of two or more parameters, either zero or one can be used, but not more. This dependency can also be found in the YouTube search operation mentioned above, involving four input parameters forContentOwner, forDeveloper, forMine and relatedToVideoId:
6. Arithmetic/Relational
Two or more parameters are related by means of arithmetic (+, –, ×, ÷) or relational (<, ≤, >, ≥, =, ≠) operators. The most common shape of this dependency pattern is two parameters where one must be greater than or equal to the other, i.e., p1 ≥ p2. This happens with dates, times, IDs, prices, etc.
Other patterns are also possible. For example, in the Yelp API, when searching for businesses, the sum of limit + offset (parameters for paginating the results) must be less than or equal to 1000, otherwise the API returns an error: “Using the offset and limit parameters, you can get up to 1000 businesses from this endpoint if there are more than 1000 results. If you request a page out of this 1000 business limit, this endpoint will return an error”.
7. Complex
This pattern is simply a combination of two or more of the previous patterns. Based on our review, it is typical to see combinations of the Requires and the OnlyOne dependencies. See the following example from the Tumblr API. A post can be of different types, depending on the value of the type parameter. If type='video', then either the embed or the data parameter must be included too.
Some stats
Some of these dependencies are more common than others. For example, Requires and ZeroOrOne dependencies are very recurrent across the APIs analyzed in our study [1], while Or and Complex are not so much. See the following charts for a summary.
If you want to know more about the dependencies found in our study [1], the dataset is freely available for anyone interested [2].
Wrap-up
In this post, we discussed the importance of inter-parameter dependencies in RESTful APIs and their lack of support in API specification languages like OAS. Then, we reviewed the most common patterns of dependencies that can be found in the wild. Hopefully, this catalogue will serve as the basis for future proposals on modeling and analyzing inter-parameter dependencies in web APIs, which could eventually be integrated into current tools for the automated development, testing and monitoring of REST APIs.
References
[1] A. Martin-Lopez, S. Segura, A. Ruiz-Cortés. 2019. A Catalogue of Inter-parameter Dependencies in RESTful Web APIs. International Conference on Service-Oriented Computing. [Available online].
[2] Inter-parameter dependencies in RESTful APIs [Dataset] . [Available online].
