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.
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.
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.
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.
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
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,
Toggling migrations with the query string is ONLY available for JSONP requests. Use the header mechanism for all other requests.
|Key||Migration (name)||Description||End-Of-Life Date|
||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||Should your app downgrade tokens' scopes if they have more permissions than you are currently requesting?||2014-07-21|
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
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:
Under “Extended scopes”, specify the extended scopes your application uses. For instance:
View your currently authorized apps and deauthorize your app for your account.
Add the Migration override header to the OAuth request when you request scopes.
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).
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.