Lookup and references

References refer to relationships or dependencies between different entities within the API. These references establish connections between resources, allowing for the retrieval, manipulation, or interaction with related data.

Lookups refer to the process of retrieving specific information or data from a dataset based on defined criteria or identifiers. These lookups enable users or applications to search for and extract relevant information efficiently. Lookups involve querying API using parameters such as unique identifiers, keywords, or filters to retrieve specific records or entities. Lookups are fundamental for accessing and retrieving targeted data within an API, facilitating effective data retrieval and manipulation operations.

Adeptia introduces the following extension configuration within the Open API extensions to specify the reference configuration.

Extension: Reference

Static Reference definition

Field name	Description	YAML
reference	Top-level key representing a collection of reference settings.	<ch:codesample> </ch:codesample>
ReferenceIdentifier	Sub-key indicating a specific reference identifier.	<ch:codesample> </ch:codesample>
operationId	The operationId of the endpoint to be invoked to fetch the records related to the reference.	<ch:codesample> </ch:codesample>
referTrigger	Trigger identifier for the trigger definition to be used to fetch the records associated with the reference.	<ch:codesample> </ch:codesample>
recordsPath	Path specifying the location of records related to the reference.	<ch:codesample> </ch:codesample>
idField	The field containing the unique identifier for the reference record.	<ch:codesample> </ch:codesample>
nameField	The field containing the name or label for the reference record.	<ch:codesample> </ch:codesample>

To reference the configuration defined in the YAML structure within an entity schema, you can use the below extension.

Below is an example of how you can define such an extension:

In this YAML structure:

• Entity: This is the name of a specific schema, representing an entity within the API.

• type: object: Indicates that the Entity schema is an object type.

• properties: This key defines the properties or attributes of the Entity schema.

• 'ReferenceEntity': This is a property name within the Entity schema.

• x-adeptia-reference: This is an extension used by Adeptia to specify a reference to another entity.

• $ref: '#/x-adeptia-extensions/reference/ReferenceIdentifier': This is a reference pointer that specifies the referenced entity.

Example: Account entity referring to the Customer

Dynamic Reference definition

For dynamic schemas, reference identification attributes must be configured within the dynamic schema strategy definition. This configuration is utilized by the dynamic schema generation strategy to identify potential reference fields within the schema and set them up accordingly.

Field name	Description	YAML
reference	Sub-key defining settings related to referencing other entities or resources.	<ch:codesample></ch:codesample>
identifier	Sub-key defining settings related to the identifier of the reference. value: JSONPath representing the reference entity. If the given path has some value then the field is considered as a reference label: Field representing a label or human-readable name associated with the reference identifier.	<ch:codesample> </ch:codesample>
operationId	The operationId of the endpoint to be invoked to fetch the records related to the reference	<ch:codesample> </ch:codesample>
recordsPath	Path specifying the location of records related to the reference	<ch:codesample> </ch:codesample>
idField	The field containing the unique identifier for the reference record	<ch:codesample> </ch:codesample>
nameField	The field containing the name or label for the reference record	<ch:codesample> </ch:codesample>

Example: Dynamic Reference definition for Salesforce connector

This structure defines configuration settings for the 'FlatFields' dynamic schema generation strategy regarding reference identification and field extraction within the schema.

dynmaicSchemaStrategies: Under the x-adeptia-extensions namespace, this section defines strategies for generating dynamic schemas.

• 'FlatFields': This is the name of a specific dynamic schema generation strategy.

  • reference: Within the 'FlatFields' strategy, this section configures settings related to referencing other entities or resources.

    • identifier: This subsection specifies attributes for identifying references.

      • value: This field uses a JSON path expression ($['referenceTo']) to extract the value of the reference identifier.

      • label: Similarly, this field extracts the label associated with the reference identifier using a JSON path expression ($['referenceTo']).

    • nameField: Specifies a JSON path ($['Name']) to extract the name field from the schema.

    • idField: Specifies a JSON path ($['Id']) to extract the ID field from the schema.

    • operationId: This field is set to 'sfQuery', indicating the operation identifier associated with the reference.

    • recordsPath: Specifies a JSON path ($['records']) to locate related records within the schema.

Lookup Configuration

No explicit configuration is needed for lookups. Any reference to the entity is inherently considered a lookup. The parameters specified in the defined trigger within the reference definition are utilized to conduct the lookup based on the specified criteria.

For example: Consider the following reference definition:

And below AllCustomer trigger definition:

The parameters from the AllCustomer trigger endpoint are utilized to perform lookup fields that refer to the customer entity.

In this scenario, the parameters section defines two parameters. One parameter's visibility is set to false, while the other one is set to true. Visible parameters are accessible for lookup operations.

For instance, there is a parameter named "Query" visible in the mapping lookup.