Entity path variables let you inject both static configuration and dynamic runtime values into API call paths. Variables are defined in entitypath and replaced by the adapter library when a call is made.
{base_path} — Replaced with the base_path property from theItential Platform service instance configuration.{version} — Replaced with the version property from theItential Platform service instance configuration.Setting these in the service instance configuration means you only need to update them in one place if they change, rather than updating every action.
{pathv#} — Replaced with the corresponding element from the uriPathVars array passed in with the request. {pathv1} maps to the first element (index 0), {pathv2} to the second, and so on. Generic adapter calls support up to 20 path variables, though calls with that many are uncommon.{query} — Replaced with query parameters from the uriQuery object on the request. The adapter library assembles the query string automatically.The first path is static and returns all devices. The second accepts a dynamic device ID, so the same action can resolve to /api/v1/devices/abc123 on one call and /api/v1/devices/def456 on the next. The third adds query parameters, allowing a call like /api/v1/devices/abc123?return_field=name,id,interfaces. The fourth supports two dynamic segments, resolving to something like /api/v1/devices/abc123/interface/eth_101.
You can use {version} for most actions while hard-coding a version for actions that require a specific API version:
The same pattern applies to {base_path}:
You can define a different schema for the request and response on every action. This is useful when:
The field name in the schema is theItential Platform name for the data. The external_name is the name the external system uses for the same field. For example, if the external system returns a token in a field called access_token butItential Platform expects token, the response schema maps access_token → token automatically.
action.json
Request schema
Response schema
The external_name field also supports dot notation for nested fields. If access_token is nested inside a credentials object, set external_name to "credentials.access_token".
The adapter supports the following datatypes:
PLAIN — Plain text. Never translated.XML — XML data. Not translated.XML2JSON — XML data that is translated to JSON before being returned toItential Platform.URLENCODE — Data that is URL-encoded before being sent to the external system.FORM — Data sent as a form submission.JSON — JSON data, translated based on the schema. This is the default.If an unsupported datatype is specified, the adapter falls back to PLAIN.
By default, an action uses the global request.attempt_timeout from theItential Platform service instance configuration. You can override this per action when you know a particular call will consistently take more or less time than the global setting.
The key field in responseObjects is a JSONQuery string that locates the relevant data within the response. Use it to strip metadata and return only the dataItential Platform needs.
The key field is a static setting. It only works when the target data is always found at the same location in the response.
Mock data files defined in action.json allow the adapter to run in standalone mode without connecting to the external system. Each mockFile value is the relative path to a file that returns data mimicking what the external system would return. For more information, see Mock data overview.
The following fields are still supported in the codebase but should not be used.
querykey — Previously used to specify the key to insert before a query string. Instead, insert the query key directly in entitypath:
Or provide the query key in the query object passed to the adapter method.