Skip to main content
Version: 4

Dynamic schema

The x-adeptia-dynamic-schema extension in Adeptia OpenAPI v3 YAML document is a custom extension designed to facilitate dynamic schema fetching for entities in an application connector.

This extension is particularly useful in scenarios where the schema of the data to be processed can vary or needs to be fetched dynamically based on certain parameters or conditions. The purpose of this extension is to define the input fields required to fetch schema for entities dynamically, specifying the operation ID of the endpoint that should be hit to retrieve the schema.

Understanding x-adeptia-dynamic-schema​

In the provided YAML example, thex-adeptia-dynamic-schemaextension is used within the schema object under a specific path (/Leads) and HTTP method (get).

  • This extension specifies an operationId("getLeadsSchema"), which is a unique identifier for an operation in the OpenAPI specification.

  • The operationId is used to identify the specific operation that should be called to dynamically fetch the schema for the entity in question, in this case, leads.

Here's a breakdown of the provided YAML example:

  • paths: Defines the available paths or endpoints in the API.

  • /Leads: Specifies the endpoint for accessing leads.

  • get: Indicates that this endpoint supports the HTTP GET method.

  • responses: Describes the possible responses for this endpoint.

  • '200': Represents a successful response with a status code of 200.

  • description: Provides a brief description of the response.

  • content: Specifies the content type of the response.

  • 'application/json': Indicates that the response will be in JSON format.

  • schema: Defines the schema of the response.

  • x-adeptia-dynamic-schema: Custom extension for dynamically fetching schema.

    • operationId: Identifies the operation to be invoked for retrieving the schema, in this case, "getLeadsSchema"
InformationBy leveraging this extension along with the operationId, developers can build more flexible and adaptable APIs that can retrieve schema information dynamically based on the specified operation.

Purpose and Usage of OperationId​

The operationId is a standard field within the OpenAPI specification that uniquely identifies a specific operation or endpoint within the API. It serves as a reference point for developers to interact with the API programmatically. Here's how it is used:

  1. Unique Identification: Each operation in the API should have a unique operationId. This allows developers to refer to specific operations without ambiguity.

  2. Programmatic Interaction: Developers can use the operationId to make API calls to the corresponding operation.

  3. Documentation: The operationId provides a clear and standardized way to document and reference operations within the API documentation. This makes it easier for developers to understand the purpose and functionality of each operation.

Conclusion​

The x-adeptia-dynamic-schema extension, combined with the operationId, provides a powerful mechanism for defining dynamic schema fetching in an OpenAPI specification.

This approach allows for more flexible and dynamic API designs, where schemas can be retrieved and applied at runtime based on the operation being performed. It is particularly useful in complex or highly dynamic systems where the structure of the data may change frequently or needs to be adaptable based on context.