Migration Guide -- Updating from media_url to source_config and from callback_url to notification_config

By Aaron Wilson, Software Engineer - June 2, 2022

Introduction

Rev AI received an update on May 5, 2022 introducing two important new options for submitting jobs: source_config and notification_config. These parameters provide additional security and add the ability for users to include authorization headers for secure end-to-end handling of customer-provided URLs.

source_config will replace the media_url parameter and notification_config will replace the callback_url parameter. These new fields are encrypted at rest and in transit. They will also not be returned with the job information (GET /jobs endpoints) for added security.

This change is especially important for users taking advantage of Rev AI HIPAA compatibility. HIPAA-authorized users will be required to use these new, more secure options when submitting jobs.

Before:

Copy
Copied
{
  "media_url": "https://www.rev.ai/FTC_Sample_1.mp3",
  "callback_url": "https://www.example.com/callback"
}

After (with optional authorization headers):

Copy
Copied
{
  "source_config": {
    "url": "https://www.rev.ai/FTC_Sample_1.mp3",
    "auth_headers":
    {
      "Authorization": "Bearer <token-to-access-source-url>"
    }
  },
  "notification_config": {
    "url": "https://www.example.com/callback",
    "auth_headers":
    {
      "Authorization": "Bearer <token-to-access-notification-url>"
    }
  },
}

Using Authorization Headers

Each new parameter provides the option of including user-provided authorization headers. Users will now be able to require authorization to access the URLs provided for source media or webhooks. If authorization headers are required to access the source_config or notification_config URLs, users should include the auth_headers option, described in the API submission docs. This allows Rev AI access to these protected URLs. The auth_headers parameter is optional and may always be omitted if not needed.

Currently, only the "Authorization" header is supported. The value of the header should be in the form <scheme> <token>. If the "Authorization" header entry is missing or the value is formed incorrectly, the request will return an error.

Below is an example source_config entry with an authorization header to access the example URL. notification_config entries should use the same format:

Copy
Copied
{
  "url": "https://www.example.com",
  "auth_headers":
  {
    "Authorization": "Bearer <token-to-access-source-url>"
  }
}

Deprecation and Version Compatibility

With this update, media_url and callback_url have been deprecated. We encourage all users to switch over to the new parameters, source_config and notification_config, at their earliest convenience. There is no planned date for the removal of media_url and callback_url parameters in the API, but future updates to our SDKs may not include support for these parameters.

For any specific product please refer to the Semantic Versioning guidelines. Minor and patch version updates will not include breaking changes and should make updating easy for our users.

At some point in the future, the deprecated options will be removed. This will likely manifest in a future API version update such as v2.

Upgrading the SDKs

Each of the official SDKs (Node, Python, and Java) has examples on how to take advantage of the new parameters on the linked documentation pages. Follow the guides below to update your specific SDK version:

Node

The new parameters were introduced in Node SDK version 3.2.0. The latest version information can be found on npmjs.com.

To install the latest package, run npm update revai-node-sdk.

See the example submission with the new parameters on the Node SDK GitHub page.

Python

The new parameters were introduced in Python SDK version 2.16.0. The latest version information can be found on pypi.org.

To install the latest package, run pip install --upgrade rev-ai or upgrade the rev-ai entry version in your requirements.txt file.

See the example submission with the new parameters on the Python SDK GitHub page.

Java

The new parameters were introduced in Java SDK version 2.2.0. The latest version information can be found in the Maven repository.

To use the new features, update the version of the Maven artifact to the latest version. It should look like the following:

Copy
Copied
<dependency>
    <groupId>ai.rev</groupId>
    <artifactId>revai-java-sdk</artifactId>
    <version>2.2.0</version
 </dependency>

See the example submission with the new parameters on the Java SDK GitHub page.