Retrieval Operation

_{Published: 27 January 2024}

Known Uses

Retrieval Operation is a very common pattern and is described in detail and elaborated upon in the book. Next to GraphQL, OData is a query-based API protocol standardized and managed by OASIS: https://www.odata.org/documentation/. Many companies, like SAP and Microsoft, offer OData APIs out of the box. OData provides advanced filer options, and it’s possible to define custom actions to execute robust queries.

Known uses in Dutch government:

• https://developer.overheid.nl/apis/cbs-odata/specificatie/production: In combination with the CBS Open Data API (https://developer.overheid.nl/apis/cbs-cijfers/specificatie/production), one can retrieve Articles, Pages, Figures, Events, and Flash content from the CBS website. These APIs unlock statistical data that can be efficiently retrieved using the OData protocol.
• https://developer.overheid.nl/apis/kadaster-bag-individual/specificatie/production: This API supports time traveling via query parameters. Information about a resource may change over time. Time traveling is a default mechanism to request information about a specific moment in time. From the perspective of time traveling using an API, there are three important moments in time:

1. Valid: This is a moment in time on which the data returned is valid in reality.
2. Available: This is a moment in time on which the data returned is available using the same API.
3. Effective: This is a moment in time on which the data returned became legally effective.

The above time traveling example matches the Time-Bound report variant as described in the book.

Discussion Input

It is difficult to balance client-side flexibility and data model clarity. Some OData services expose large numbers of attributes, making it hard to understand the data model. Creating multiple Retrieval Operations can help scope the data model, but it remains challenging to determine optimal scopes for Retrieval Operations

Another point of discussion is the HTTP verb that should be used for Retrieval Operations It is possible to include a payload in a GET request, but it is not common practice nor recommended according to HTTP specifications. GET requests are primarily used to request data from a specified resource and should not have a payload in the usual sense. For complex queries, the POST operation as catch all method is used instead. But this is using a non-idempotent operation in an idempotent manner. That’s why recently, the QUERY method came into place as a new HTTP method for safe, idempotent query functionality with a request payload.

Recommended Reading

More information is available online:

• https://evertpot.com/get-request-bodies/
• https://nordicapis.com/your-guide-to-the-new-http-query-method/