5.5.1. Retrieve

The operation retrieve in case of an object will fetch the data of an object.

Different entity types are available within the objectStructure, for example motorVehicle or building. You can find a complete overview in AFD 2.0 online.

How to use variants

The operation retrieve is a webservice call without a body. Fields, containing an array of attribute names, and a filter, containing an attribute name, operator and value, are part of the query parameter in the request.

The example below shows the query parameters for a motor vehicle.

_fields=licensePlate,chassisNumber,reportCode&_filter=licencePlate|EQ|AA-58,chassisNumber|EQ|LGLW24

For more information see Retrieve operations and Query parameters in the Design principles paragraph.

The output of the operation ‘retrieve’ uses the objectStructure as described in the objectStructure section.

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 object information in an object structure

The variant default retrieves object information based on a unique reference, using the objectStructure. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes. More information on query parameters is available in Design principles.

Endpoint definition

The {objectName} is part of the endpoint below. In real life endpoints you should use the entityType of the object instead, for example the entityType motorVehicle or building (see AFD 2.0 online). If it is required to make a distinction between different endpoints for one entityType, the {objectName} should also contain an attribute. Examples: {objectName} = motorVehicle.licensePlate or {objectName} = motorVehicle.make.

Method	Endpoint	Request	Query parameter(s)	Response	Remarks
GET	{ uri } /objects/{objectName}/retrieve	N/A	_fields=[{attribute}], _filter=[{attribute}|{operator}|{valueAttribute}]	objectStructure

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.
object		O	Depending on the requested entity type.

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

list – Obtain reference information of available objects according to a query statement

The variant list is used to retrieve a list of objects. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.

Endpoint definition

If the complete object is subject to the operation retrieve, no path parameter is included in the endpoint. This is shown in the table below. More information on query parameters is available in Design principles.

Method	Endpoint	Request	Query parameter(s)	Response	Remarks
GET	{ uri } /objects/list	N/A	_fields=[{attribute}], _filter=[{attribute}|{operator}|{valueAttribute}]	objectStructure

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.
object	refKey	O	Unique reference key assigned to an entity.

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