Wish List

_{Published: 16 May 2023}

Known Uses

The Wish List pattern is widely used in Dutch government APIs. The guidelines for use of this pattern are available online in Section 9 (“Customization”) of “API Designrules Extensions”.

Government APIs are available via a public developer portal. Please find below some examples of Dutch government APIs that make use of the fields parameter for custom representation:

1. https://developer.overheid.nl/apis/kadaster-bag-current/specificatie/production
2. https://developer.overheid.nl/apis/logius-cor/specificatie/production

In the Dutch Energy sector I am currently working in, we are about to design APIs that utilize the combination of the fields parameter with the expand parameter. In HAL-formatted responses (responses with links to associated resources) the consumer can retrieve subfields of the associated resource by expanding the returned HAL link. Design rules are available in the Dutch document “API-strategie”. There is no concrete API yet.

Discussion Input and Recommended Reading

Discussion points:

• To distinguish between “real” query parameters and the more “steering” or “meta” parameters like expand, fields, limit and page, we – the Dutch Energy sector API Working Group – advocate the usage of an underscore prefix, so _fields, _expand, _limit and _page to prevent misinterpretation of the function of the query parameters.
• The Wish List works in “optima forma” or comes to his right if all the response fields are optional. If there are any required fields in the response, the question arises if these fields should be returned in case they are not requested in the Wish List;
• The implementation in provider service layers of the Wish List is expensive – sometimes these costs are simply too high and is there no business case to justify the investment.

Some other sources that mention the Wish List pattern:

• “Zalando RESTful API and Event Guidelines”, http://opensource.zalando.com/restful-api-guidelines/#157
• “REST API Design Rule Book” by Masse (2011), p74: “The fields query parameter allows clients to request only the resource state information that it deems relevant for its particular use case. The REST API must parse the request’s query parameter’s inclusion list and return a partial response”.