Migrations

We reserve the right to make incremental changes to the API as we deem necessary. In order to make it possible to change the API but still support legacy applications, we will make use of migrations. Migrations are a per-app feature that developers may toggle for their own apps from the time that the old behavior is deprecated until the time that it has reached the end of its life (EOL). Once the EOL date is reached, the migration will be enabled for all apps with no legacy mode available.

Accessing Migration Data

We offer a single toggle for each migration and app that will globally turn the migration on (current mode) or off (legacy mode) for that app as well as a per-call header mechanism that overrides the global behavior.

Global Toggle

You can toggle the global migration behavior of your apps by editing your apps listed at https://account.app.net/developer/apps/.

By default, new apps will come with all existing migrations toggled to “Current” mode. This reflects the fact that support for legacy mode will eventually be removed. However, any migrations that are released after the app is created will be initially toggled to “Legacy” mode, so app developers can expect that the API behavior will not unexpectedly change for existing apps.

Per-call Toggle

In addition to using the edit app toggles, we offer the X-ADN-Migration-Overrides header as a way for developers to override migration behavior on a per-call basis. This header should contain a query-string encoded list of valid migration keys and values (0 or 1). For example, providing X-ADN-Migration-Overrides: foo=0 would disable the migration named foo. We expect that some apps may be distributed in such a way that some users may be running old versions while others are running newer versions, so this override header may make it easier to adopt new functionality without causing regressions. As with the toggle, though, migration override keys cannot be used past their EOL dates. Also, X-ADN-Migration-Overrides is whitelisted for CORS, so we expect that it should be usable in all contexts.

Migration Response Header

All calls to our endpoints will return X-ADN-Migrations-Enabled, a query-string encoded list of migration keys that are enabled for that particular API call. This list will take into account globally toggled migrations as well as those enabled by X-ADN-Migration-Overrides.

Using Migrations with JSONP

For JSONP requests we offer the ability to override the default migration behavior on a per-call basis. To do this, add a list of valid migration keys and values (0 or 1) to the query string. For example, https://api.app.net/posts/stream/global?callback=json_callback&foo=0

Toggling migrations with the query string is ONLY available for JSONP requests. Use the header mechanism for all other requests.

Current Migrations

Key Migration (name) Description End-Of-Life Date
extended_scopes Extended scopes Rewrite the messages, public_messages, and files permissions that apps request to use only the content types provided. This allows you to migrate your app to use extended scopes without you having to immediately change your app's code. Please see the migration guide for more information.
allow_scope_downgrade Allow Scope Downgrade Should your app downgrade tokens' scopes if they have more permissions than you are currently requesting? 2014-07-21

Extended Scopes Migration Guide

Extended scopes help users keep their data more secure by only allowing apps to access a subset of their files or channels. Since many apps have already been released which request the files, messages, or public_messages scopes, this migration allows the app to continue to request those scopes, but App.net will only grant the extended scopes that the app has registered with App.net. To migrate your app, you need to:

  1. Go to your App dashboard.
  2. Select the app you want to migrate.
  3. Click “Edit this App.”
  4. Under “Extended scopes”, specify the extended scopes your application uses. For instance: messages:net.app.core.pm, messages:net.patter-app.room.

    Extended Scopes Migration

  5. View your currently authorized apps and deauthorize your app for your account.

    Deauthorize your app

  6. Add the Migration override header to the OAuth request when you request scopes.

    X-ADN-Migration-Overrides: extended_scopes=1

  7. Verify that user can still do everything you expect in your app with the extended scopes.
  8. On the screen where you specified extended scopes for your app, flip the “Extended scopes” migration to “Current.” This will turn on the behavior for all requests coming from your app (including the currently released version).

    Extended Scopes Migration Activated

  9. Ship a new version of your app that requests extended scopes instead of the files, messages, or public_messages scopes.

This migration only affects newly created tokens. Any users that currently have the old scopes will not be affected by this migration. Eventually, App.net would like to work to downgrade those old tokens.