SPI version negotiation

Starting with version 4.4.0 of i2 Analyze, your connectors can negotiate with the gateway to establish a common understanding of which version of the i2 Connect SPI to use.

By default, the gateway assumes that your connector will use version 1.0 of the SPI. When 1.0 is the correct version for your connector, you don't need to do anything. If you rely on a later version of the SPI, you can both determine what versions the server supports, and respond with the version that you want to use.

For more information on the differences between SPI versions, refer to the SPI changelog.

Server-supported SPI versions

All HTTP requests to your connector from i2 Analyze version 4.4.0 and above contain a header named I2-Spi-Versions. The value of the header is a comma-separated list of the SPI versions that the server supports.

Connector specification of SPI version

To specify the SPI version that it wants to use, a connector can add a field named version to its response from the configuration endpoint. For example:

{
  "version": "1.0",
  "defaultValues": {
    "timeZoneId": "Europe/London",
    ...
  },
  "services": [
    ...
  ]
}

Java example

The following code is taken from ConnectorController.java in the sample solution code for the NYPD connector. In implementing the configuration endpoint, it extracts the supported SPI versions from the HTTP headers, and outputs some diagnostic information:

private static final int CONNECTOR_MAJOR_VERSION = 1;
private static final int CONNECTOR_MINOR_VERSION = 2;

/**
 * Defines the /config endpoint which acquires the connector configuration data.
 *
 * @return The config.json file.
 */
@RequestMapping(method = RequestMethod.GET, value = "/config", produces = APPLICATION_JSON_VALUE)
public Resource config(@RequestHeader(value = "I2-Spi-Versions", required = false) List<String> gatewaySupportedVersions) {
  if (gatewaySupportedVersions == null) {
    return configResource;
  }
  System.out.println("Latest gateway supported versions: " + gatewaySupportedVersions);

  for (String supportedVersion: gatewaySupportedVersions) {
    final String[] supportedVersionParts = supportedVersion.split("\\.");
    final double supportedMajorVersion = Double.parseDouble(supportedVersionParts[0]);
    final double supportedMinorVersion = Double.parseDouble(supportedVersionParts[1]);

    final String connectorVersion = CONNECTOR_MAJOR_VERSION + "." + CONNECTOR_MINOR_VERSION;
    if ((CONNECTOR_MAJOR_VERSION == supportedMajorVersion) && (CONNECTOR_MINOR_VERSION <= supportedMinorVersion)) {
      System.out.print("The gateway supports connector version " + connectorVersion + "\n");
    } else {
      System.out.print("The gateway does not support connector version " + connectorVersion + "\n");
    }
  }
  return configResource;
}

Python example

The following code is taken from controller.py in the sample solution code for the NYPD connector. In implementing the configuration endpoint, it extracts the supported SPI versions from the HTTP headers, and outputs some diagnostic information:

connector_major_version = '1'
connector_minor_version = '2'

@controller.route('/config')
def config():
    config = send_from_directory('static', 'config.json')
    gateway_supported_versions = request.headers.get('I2-Spi-Versions')

    if gateway_supported_versions is None:
        return config

    print('Latest gateway supported versions: ' + gateway_supported_versions)

    for supported_version in gateway_supported_versions.split(','):
        supported_version_parts = supported_version.split('.')
        supported_major_version = supported_version_parts[0]
        supported_minor_version = supported_version_parts[1]

        connector_version = connector_major_version + '.' + connector_minor_version

        if (connector_major_version == supported_major_version) and (connector_minor_version <= supported_minor_version):
            print('The gateway supports connector version ' + connector_version)
        else:
            print('The gateway does not support connector version ' + connector_version)

    return config