Introduction
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.
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).
PayPal example
//PayPay-Create invoice
IF custom.label THEN custom.amount;
IF minimum_amount_due THEN allow_partial_payment==true;
Google Map example
IF rankby=='distance' THEN NOT radius;
IF rankby=='distance' THEN Or(keyword, name, type);
minprice<=maxprice;
IF radius THEN NOT rankby;
Github example
//Github - Create deployment status
IF state=='inactive' THEN Accept LIKE '*application/vnd.github.ant-man-preview+json*';
IF state=='in_progress'|'queued' THEN Accept LIKE '*application/vnd.github.flash-preview+json*';
IF log_url THEN Accept LIKE '*application/vnd.github.ant-man-preview+json*';
IF environment THEN Accept LIKE '*application/vnd.github.flash-preview+json*';
IF environment_url THEN Accept LIKE '*application/vnd.github.ant-man-preview+json*';
IF auto_inactive THEN Accept LIKE '*application/vnd.github.ant-man-preview+json*';
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”.
IDL example
Or (description, title)
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”.
IDL example
OnlyOne (From, MessagingServiceSid)
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:
IDL example
AllOrNone (subject_id, subject_type)
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:
IDL example
ZeroOrOne (forContentOwner, forDeveloper, forMine, 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”.
IDL example
limit + offset <= 1000
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, while Or and Complex are not so much. See the following charts for a summary.
References
[1] Martin-Lopez, A., Segura, S., Ruiz-Cort´es, A.: A catalogue of inter-parameter dependencies in restful web apis. In: Yangui, S., Bouassida Rodriguez, I., Drira, K., Tari, Z. (eds.) Service-Oriented Computing. pp. 399–414. Springer International Publishing, Cham (2019)