Set Up for Sources
Instructions for how to get started with the Interactions API as a Source
The best and fastest way the DDx API Team communicates with Sources is via joint Slack channel so we can provide support with set up and management of connections to the Interactions API as a Source.
To create a joint Slack channel, please reach out to [email protected] with your organizational name and emails of individuals to be added as members of the channel.
Creating an Interactions App
An Interactions API App allows you to create Sandbox Keys to test your integration with the Interactions API, and later for Data Owners to provision production API Keys to you.
To create an Interactions App, you will need to log in to your Console Dashboard, navigate to "Applications Manager" and select + New App. After selecting the Interactions API, you will name your App and generate a Sandbox Key.
When your App is available in Production, you will see a list of API Keys provisioned to you along with their associated Workspace, pubic key ID, and any given expiration date.
A detailed guide for App creation can be found here .
Creating and Using a Sandbox Key
A Sandbox Key for the Interactions API allows you to test your setup to the Interactions API. Requests to the Interactions API with Sandbox Keys will not be forwarded to any destinations, but they will generate API status codes.
To create a Sandbox Key, log in to the Console, click on your App to view the App Details page, and click Generate Sandbox Key. Here you will name your Sandbox Key and set an expiration date. Sandbox Keys are only viewable once.
Once you have verified that your setup is working as intended, you can inform the DDx API Team that you are ready to send production traffic via the shared Slack group.
More information about creating a sandbox key can be found here .
How to set up an Interactions API integration
The Interactions API receives requests at this URL: https://api.movementinfrastructure.org/v1/
Sending data to the Interactions API requires a valid API Key from a Data Owner. API requests must also be formatted in one of the Interactions API's accepted formats. The current version of the data formats the Interactions API accepts can be found here.
Source authenticates with the Interactions API via Basic Authentication headers. Sources may use any username they want, but must use their provisioned API Keys as the password/credentials.
Sending data to the Interactions API
The DDx API's Interactions API receives valid API requests, validates them, and delivers them to intended Destinations based on the properties of the API Key.
The Interactions API is able to validate fields and objects in the main body of the request. The Interactions API also supports receiving a metadata_json field, which can contain additional fields not specified in specific API contracts. The Interactions API can receive individual objects or arrays of objects.
For more details on SLAs and replay needs, reach out to [email protected] or via joint Slack channel.
Use of the Interactions API
The use of API Keys
API Keys are production credentials that grant access to the Interactions API. Data owners (i.e., your users) should provide API Keys to you once they are ready for you to send data to their intended destinations. Data owners should also make sure to clarify which destinations are tied to a specific API Key.
API Keys correspond to one data owner, one source, and one to many destinations.
- Unless otherwise specified, requests that you send to the Interactions API will be delivered to all destinations associated with an API Key without any additional configurations needed in the request.
Sources will automatically receive responses from the Interactions API in the form of HTTP status codes.
- Sources will not automatically be notified if their data was successfully delivered to the destinations specified by an API Key. For more information on deliverability and feedback around successes and failures, Sources should request logs of their requests from the DDx API Team.
Usage Policies
DDx API has developed policies around acceptable use of the Interactions API in order to make sure it can best serve the needs of all of its users. These policies govern DDx API's approach to data security, rate limiting, data quality, volume, etc. The latest version of these policies will be shared with you as part of your onboarding.
Updated 25 days ago