Documentation
A newer release of the API3 Technical documentation is available.

# Specification

Table of Contents

The Oracle Integration Specification (OIS) is based on Open API specification (OAS) (opens new window), but there are some differences, be sure to focus on the following documentation when working on an OIS file.

OAS

It is not recommended to refer to OAS for help while creating an OIS object. OIS only borrows formatting practices from OAS. Everything needed to create an OIS object is in these docs.

See the article Setting Oracle Integration Standards (opens new window) for an overview of OIS.

  • Fields denoted by (*) are for documentation purposes and not used by an Airnode.
  • The OIS fields should be reviewed and customized by the integrating party.
  • All URLs are absolute (i.e., relative URLs (opens new window) are not supported).

# OIS Object Summary

An OIS has five root fields (keys).

  1. oisFormat
  2. title
  3. version
  4. apiSpecifications
  5. endpoints

apiSpecifications describe the API's operations which are mapped to the endpoints that Airnode exposes on-chain.

{
  "oisFormat": "1.0.0",
  "title": "myOisTitle",
  "version": "1.2.3",
  "apiSpecifications": {
    ...
  },
  "endpoints": [
    ...
  ]
}
1
2
3
4
5
6
7
8
9
10
11

# 1. oisFormat

(Required) The OIS format version followed while generating the specifications.

Be sure to use the correct OIS version for the Airnode version you are deploying.
Airnode version Latest compatible OIS version
0.2.x through 0.7.x 1.0.0 (opens new window)
0.8.x 1.1.2 (opens new window)
0.9.x 1.2.0 (opens new window)
0.10.x 1.4.0 (opens new window)

# 2. title

(Required) The OIS title. Title field is at most 64 characters, can only include alphanumeric characters, hyphens, underscores and whitespaces.

# 3. version

(Required) A user defined version for the OIS object. Not to be confused with the oisFormat version which defines an OIS formatting version.

# 4. apiSpecifications

(Required) An object specifying the API with the following root level fields:

// apiSpecifications
{
  "servers": [
    {
      "url": "https://myapi.com/api/v1"
    }
  ],
  "paths": {
    "/myPath": {
      "get": {
        "parameters": [
          {
            "name": "myParameter",
            "in": "query"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "mySecurityScheme1": {
        "type": "apiKey",
        "name": "X-MY-API-KEY",
        "in": "query"
      }
    }
  },
  "security": {
    "mySecurityScheme1": []
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# 4.1. servers

(Required) An array of objects containing the base URL of the API. Only one object (i.e., base URL) is allowed in the array. Applies to all API operations.

# 4.2. paths

(Required) An object where an API's operations are defined by {path}.{method} (i.e. paths./myPath.get) each with a parameters array.

# 4.2.1. parameters

(Required) A list of the API operation's parameters, each with the following fields:

  • name
  • in
# 4.2.1.1. name

(Required) The name of the parameter.

# 4.2.1.2. in

(Required) The location of the parameter. When integrating a POST method, define the body parameters with in: query. Airnode will convert all query types into the requestBody. Note that only the non-nested application/json content-type is supported.

Allowed values: query, header, path, cookie.

# 4.3. components

info (Required) An object where security schemes can be found under securitySchemes.{securitySchemeName} with the following elements:

  • type
  • name
  • in
  • scheme

# 4.3.1. type

(Required) The type of the security scheme.

Allowed values:

  • Used by an API operation to authenticate Airnode.
    • apiKey
    • http
  • Allows an API operation to acquire information about the requester and/or the chain.
    • relayRequesterAddress
    • relaySponsorAddress
    • relaySponsorWalletAddress
    • relayChainId
    • relayChainType

# 4.3.2. name

(Only if type is apiKey) The name of the security scheme variable.

# 4.3.3. in

(Only if type is apiKey) The location of the security scheme variable.

Allowed values: query, header, cookie

# 4.3.4. scheme

(Only if type is http) The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235 (opens new window).

Allowed values: (basic and bearer).

"mySecurityScheme2": {
  "type": "http",
  "scheme": "bearer"
}
1
2
3
4

# 4.4. security

(Required) An object containing all security schemes required by an API call. Applies to all operations. A security scheme can contain information required by the API to authenticate Airnode as well as information about the requester (relay information) the API may also require. Read more about security schemes in the API Security section of the Build an Airnode guide and the Airnode Authentication section of Concepts and Definitions.

The security object maintains the names of all the security schemes used. Each security scheme in security maps to an empty list. The empty list will be used by future versions of Airnode for individual endpoint authentication. The components.securitySchemes.{name} object defines the security schemes. Unlike OAS security is an object, not an array.

// OIS object
"components": {
  "securitySchemes": {
    "my-api-key-scheme": {
      "in": "query",
      "type": "apiKey",
      "name": "access_key"
      "scheme": "<FILL_*>" // Used when type="http".
    }
  }
},
"security": {
  "my-api-key-scheme": []
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

The apiCredential object (which is not part of the OIS object) holds credentials needed by the security scheme if any.

// config.json root object.
// Not part of the OIS object.
"apiCredentials": [
    {
      "oisTitle": "my-ois-title", // Must match the ois.title field the security scheme is in.
      "securitySchemeName": "my-api-key-scheme",
      "securitySchemeValue": "${API_KEY}" // In secrets.env
    }
  ]
1
2
3
4
5
6
7
8
9

Please note:

Currently Airnode reads the security schemes from component.securitySchemes and not security. Using the security field now (in conjunction with component.securitySchemes) provides for a smooth transition to future releases of Airnode with regards to security scheme implementation. This will allow assigning of security schemes to individual API operations. Currently security schemes are assign to the entire API.

# 5. endpoints

(Required) A list of objects, each specifying an Airnode endpoint with the following fields:

Please Note

Fields denoted by * are for documentation purposes and not used by Airnode node.

// endpoints
[
  {
    "name": "convertToUsd",
    "operation": {
      "path": "/myPath",
      "method": "get"
    },
    "fixedOperationParameters": [
      {
        "operationParameter": {
          "name": "to",
          "in": "query"
        },
        "value": "USD"
      }
    ],
    "reservedParameters": [
      {
        "name": "_type",
        "fixed": "int256"
      },
      {
        "name": "_path",
        "default": "data.0.price"
      },
      {
        "name": "_times"
      }
    ],
    "parameters": [
      {
        "name": "from",
        "default": "EUR",
        "operationParameter": {
          "name": "from",
          "in": "query"
        }
      }
    ],
    "preProcessingSpecifications": [
      {
        "environment": "Node 14",
        "value": "const output = {...input, from: \"eth\"};",
        "timeoutMs": "5000"
      },
      {
        "environment": "Node 14",
        "value": "const output = {...input, from: input.from.toUpperCase()};",
        "timeoutMs": "5000"
      }
    ],
    "postProcessingSpecifications": [
      {
        "environment": "Node 14",
        "value": "const output = Math.round(input.price * 1000);",
        "timeoutMs": "5000"
      }
    ]
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# 5.1. name

(Required) The name of the Airnode endpoint, must be unique in OIS.

# 5.2. operation

(Required) An object that refers to an API operation defined in apiSpecifications.paths, has the following elements:

  • path
  • method

# 5.2.1. path

(Required) The path of the API operation.

# 5.2.2. method

(Required) The method of the API operation.

Allowed values: get, post

# 5.3. fixedOperationParameters

info (Required) A list of objects specifying the fixed parameters for an API operation. While required, the fixedOperationParameters array can be empty. Each object has the following elements:

  • operationParameter
  • value

# 5.3.1. operationParameter

(Required) An object that refers to a parameter of an API operation with the following elements:

  • name
  • in
# 5.3.1.1. name

The name of the API operation's parameter that will have a fixed value.

# 5.3.1.2. in

Must be one of three possible values (query, header, path, cookie).

# 5.3.2. value

(Required) The value to be used for the respective parameter of an API operation that cannot be overridden by the requester.

# 5.4. reservedParameters

info (Required) A list of objects that specify reserved Airnode endpoint parameters that do not map to any API operation parameters, but are used for special purposes by the Airnode. At a minimum, one object must specify the API response type i.e. it must include "name": "_type". See the Reserved Parameters doc for an in-depth explanation. Each object has the following elements:

  • name
  • fixed
  • default

# 5.4.1. name

(Required) The name of the reserved parameter. Always starts with _.

Allowed values: _type, _path or _times

# 5.4.2. fixed

(Optional) The fixed (i.e., non-overridable) value for the reserved parameter. Cannot be used together with default.

# 5.4.3. default

(Optional) The default value for the reserved parameter. Used when no value is provided. Cannot be used together with fixed.

# 5.5. parameters

info (Required) A list of objects that specify Airnode endpoint parameters that map to an particular API operation's parameters. While required, the parameters array can be empty. Each object has the following elements:

  • operationParameter
  • name
  • default
  • description *
  • require
  • example

# 5.5.1. operationParameter

(Required) An object that refers to a parameter of an API operation, has the following elements:

  • name
  • in
# 5.5.1.1. name

The name of the parameter from an API operation.

# 5.5.1.2. in

Must be one of four possible values (query, header, path, cookie).

# 5.5.2. name

(Required) The name of the Airnode endpoint parameter. Is not allowed to start with _.

# 5.5.3. default

(Optional) The default value for the Airnode endpoint parameter. Used when no value is provided.

# 5.5.4. description *

(Optional) A description of what the Airnode endpoint parameter does.

# 5.5.5. required

(Optional) If the Airnode endpoint parameter is required, a boolean value.

# 5.5.6. example *

(Optional) The example value to be used in test calls.

# 5.6. summary *

(Optional) A one sentence summary of what the Airnode endpoint does.

# 5.7. description *

(Optional) A more detailed description of what the Airnode endpoint does.

# 5.8. externalDocs *

(Optional) URL to external documentation for the Airnode endpoint.

# 5.9. preProcessingSpecifications *

(Optional) Defines the preprocessing code that can be used to modify the endpoint parameter before making the API request defined by an Airnode endpoint.

See the Pre/Post Processing doc for additional details.

# Example

"preProcessingSpecifications": [
  {
    // Execute synchronously in Node.js version 14
    "environment": "Node 14",
    // Define a new "from" parameter with value "eth"
    "value": "const output = {...input, from: \"eth\"};",
    // Run for 5 seconds maximum
    "timeoutMs": "5000"
  },
  {
    // Execute synchronously in Node.js version 14
    "environment": "Node 14",
    // Uppercase the "from" parameter defined by the previous snippet
    "value": "const output = {...input, from: input.from.toUpperCase()};",
    // Run for 5 seconds maximum
    "timeoutMs": "5000"
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 5.10. postProcessingSpecifications *

(Optional) Defines the post-processing code that can be used to modify the API response from the request defined by an Airnode endpoint.

See the Pre/Post Processing doc for additional details.

# Example

"postProcessingSpecifications": [
  {
    // Execute synchronously in Node.js version 14
    "environment": "Node 14",
    // Multiply the API return value by 1000 and round it to an integer
    "value": "const output = Math.round(input.price * 1000);",
    // Run for 5 seconds maximum
    "timeoutMs": "5000"
  }
]
1
2
3
4
5
6
7
8
9
10
Last Updated: 1/21/2023, 7:13:42 PM

← Reserved Parameters →