API-Connection-Management.md

API Connection Management

The Quick Start exercise supplies all connection information explicitly as command-line arguments, however to better operationalize the API Publisher you should create a Configuration Store to securely configure named API connections, and to track the state of publishing between various source and target APIs.

The Configuration Store implementation can be selected by passing the --configurationStoreProvider command-line argument, by setting the EdFi:ApiPublisher:ConfigurationStore:Provider environment variable, by modifying the provider value in the configurationStoreSettings.json file (in that order of precedence).

{
  "configurationStore": {
    "provider": "postgreSql",
    "sqlServer": {
      "connectionString": "Server=(local);Database=EdFi_API_Publisher_Configuration;Trusted_Connection=True"
    },
    "postgreSql": {
      "connectionString": "Server=localhost;Port=5432;Database=edfi_api_publisher_configuration",
      "encryptionPassword": ""
    },
    "awsParameterStore": {
      "Profile": "default",
      "Region": "us-east-1"
    },
    "plainText": { }
  }
}

Currently there are four configuration store implementations available:

Setting Value	Implementation	Description
sqlServer	Configuration Store for SQL Server	Reads API connection details from and writes successfully published changed version numbers to a SQL Server configuration table. Enables management of individual connection settings with encryption for securely storing keys and secrets using the built-in support for symmetric key encryption in SQL Server.
postgreSql	Configuration Store for PostgreSQL	Reads API connection details from and writes successfully published changed version numbers to a PostgreSQL configuration table. Enables management of individual connection settings with encryption support for securely storing keys and secrets using a supplied password for symmetric key encryption using the pgcrypto extension for PostgreSQL.
awsParameterStore	Configuration Store for AWS Parameter Store	Reads API connection details from and writes successfully published changed version numbers to the AWS Systems Manager Parameter Store using the AWS region specified in the awsParameterStore property of the configurationStoreSettings.json file. It also assumes the runtime environment has been initialized with the necessary credentials for accessing AWS services. Enables management of individual connection settings with encryption support for securely storing keys and secrets.
plainText	Plain Text Configuration Store	Reads connection information defined in plain text in the plainTextNamedConnection.json file. Intended for development purposes only. Does not support writing back the successfully published Change Version.

Defining API Connections

Regardless of the configuration store implementation in use, the configuration settings needed for defining a named API connection are described below.

Parameter Name	Type	Description
/ed-fi/apiPublisher/connections/{connectionName}/url	String	The base URL of the Ed-Fi ODS API (up to, but not including, the /data/v3 portion of the URL).
/ed-fi/apiPublisher/connections/{connectionName}/key	SecureString	The key to use for API authentication.
/ed-fi/apiPublisher/connections/{connectionName}/secret	SecureString	The secret to use for API authentication.
/ed-fi/apiPublisher/connections/{connectionName}/ignoreIsolation	String	(Optional) A boolean value (true/false) indicating whether the source Ed-Fi ODS API data should be published even if it does not support an isolated context for processing through Change Query snapshots.
/ed-fi/apiPublisher/connections/{connectionName}/include	String	(Optional) For source API connections, the resources to publish to the target with their dependencies. The value is defined using a CSV format (comma-separated values), and should contain the partial paths to the resources (e.g. /ed-fi/students,/custom/busRoutes). For convenience when working with Ed-Fi standard resources, only the name is required (e.g. students,studentSchoolAssociations). The Ed-Fi API Publisher will also evaluate and automatically include all dependencies of the requested resources (using the dependency metadata exposed by the target API). This will ensure (barring misconfigured authorization metadata or data policies) that data can be successfully published to the target API.
/ed-fi/apiPublisher/connections/{connectionName}/includeOnly	String	(Optional) For source API connections, the resources to publish to the target without their dependencies. The value is defined using the same format as with --include (see above). NOTE: Use caution when publishing without automatically including all dependencies.
/ed-fi/apiPublisher/connections/{connectionName}/exclude	String	(Optional) For source API connections, the resources (and their dependents) to NOT publish to the target. The value is defined using the same format as with --include (see above). The Ed-Fi API Publisher will also evaluate and automatically exclude all dependent resources of the excluded resources (using the dependency metadata exposed by the target API). This will ensure (barring misconfigured authorization metadata or data policies) that data can be successfully published to the target API.
/ed-fi/apiPublisher/connections/{connectionName}/excludeOnly	String	(Optional) For source API connections, the specific resources to skip publishing to the target (dependent resources will still be published). The value is defined using the same format as with --include (see above). NOTE: Use caution when publishing without automatically including all dependencies.
/ed-fi/apiPublisher/connections/{connectionName}/lastChangeVersionsProcessed	String	(Optional) For source API connections, contains a JSON object, keyed by target API name, that indicates the last change version successfully published from the source to the target. This value is automatically created/updated by the Ed-Fi API Publisher after successfully completing the publishing process.

Screenshots

SQL Server Configuration

PostgreSQL Configuration

AWS Parameter Store Configuration