5.7.1. Retrieve

The operation retrieve will fetch data in a tabular structure for use in automated processes and user dialogs.

Automated processes often use codelists to enforce the use of valid values for a specific attribute and keep the dataset compact. In a screen dialog this is represented by a drop-down list which shows the available options, for example to select the car make and model for car insurance. In post process situations the codes may be used to fetch the corresponding description or text(s) defined in the codelist(s), for instance the complete text of a condition or clause which is referred to on the policy by a code.

The retrieve operation allows a party to fetch a complete table with codes and corresponding descriptions, which can be incorporated in the proprietary environment of that party.

The data is selected by providing the {tableId} as a path parameter of the endpoint.

How to use variants

The retrieve operation is a webservice call without a body. The specific table is selected by supplying the tableName as a path parameter of the end point. Required field, filter and sort options can be added as query parameters. For more information see the Retrieve operations section of the Design principles chapter.

The output of the retrieve operation uses the afsTableStructure as described in chapter afsTableStructure.

If a negative response is generated, that means the request is technically incorrect, it follows the general rules as described in the Error section of the HTTP status codes and error handling chapter.

Variants

The variant enables a differentiation in requirements to suit the specific situations (listed below), and for each variant, to which AFD structure it applies.

<default> – Obtain table (path parameter) information in an afsTable structure

This variant is used to obtain table information (with {tableId} as a path parameter) in an afsTable structure.


With the query parameter the desired fields, filter and sort can be given. If no fields are given, all fields will be returned. If no filter is given, all records of the table will be returned.

Endpoint definition

Method	Endpoint	Request	Query parameter(s)	Response	Remarks
GET	{ uri }/afstable/{tableId}/retrieve	N/A	_fields=[{attribute}] _filter=[{attribute}|{operator}|{valueAttribute}] _sort=[{attribute}]	afsTableStructure

For more information about query parameters, see Design principles

Mandatory input and/or output (I/O) attributes

Entity	Attribute	I/O	Remarks
commonFunctional	dataCatalogVersion	O	Version of the data catalog on which the message is based.
commonFunctional	functionVariant	O	The function variant is used to determine the additional set of required and optional input and output data.
commonFunctional	afdDefinitionName	O	Name of the AFD-definition.
commonFunctional	afdDefinitionVersion	O	Version of the AFD-definition.
afsTable	tableName	O	Name of the table or data set.

Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.