Update: We are pushing back the original dates listed in this post by two weeks. We will be setting all apps to “current” mode on March 27th. We will be sunsetting all existing migrations on April 3rd.

Although most of our API development effort is focused on delivering new functionality, over the last few months we’ve made a number of tweaks to the existing behavior of the API. Our strategy for making incremental changes to existing functionality in the API without breaking apps is to use migrations. Migrations allow us to introduce new behavior while allowing existing apps to operate in “legacy” mode until they’ve had a chance to update their code.

We currently have four active migrations, three of which have been active since September. These migrations are simple changes to the API and we want to get everyone up-to-date so we can reduce documentation complexity, bugs, etc. To move things along, we will be sunsetting our existing migrations on March 20th April 3rd.

This will be our first time sunsetting any migrations (and there will be new ones in the future) so we want to make sure it goes smoothly for everyone. On March 13th 27th, a week before we sunset the existing migrations (and one month from today), we will set all apps to use “current” mode for all migrations. You will still be able to set these back to “legacy” mode if anything breaks. You can check and adjust the current migration settings for your apps here. Please also check for any instances where you have overridden migration settings on a per-call basis. If all your migrations are already set to “current” and you’re not overriding anything on a per-call basis you do not need to make any changes to your code.

The following is the complete list of existing migrations, along with examples so you can review and make sure your code is good to go:

Response envelope migration - all responses are returned in a response envelope with “data” and “meta” fields.

{
    ... App.net object fields ...
}

{
    "data": {
        ... App.net object fields ...
    },
    "meta": {
        ... other useful stuff ...
    }
}

Pagination IDs migration – max_id / min_id are always returned as strings rather than ints.

{
    "data" : [
        ... App.net objects ...
    ],
    "meta":{
        "code" : 200,
        "max_id" : 953737,
        "min_id" : 927539,
        "more" : true 
    }
}

{
    "data" : [
        ... App.net objects ...
    ],
    "meta":{
        "code" : 200,
        "max_id" : "953737",
        "min_id" : "927539",
        "more" : true 
    }
}

Follow pagination migration – follower / following user lists are always paginated.

{
    "data" : [
        ... complete list of user objects ...
    ],
    "meta":{
        "code" : 200,
        "max_id" : "953737",
        "min_id" : "52",
        "more" : false
    }
}

{
    "data" : [
        ... partial list of user objects ...
    ],
    "meta":{
        "code" : 200,
        "max_id" : "953737",
        "min_id" : "927539",
        "more" : true
    }
}

Disable min/max id migration – when using pagination to request posts, pass since_id or before_id. Note also that the legacy response would include the post matching the supplied id, but the current response does not.

/stream/0/posts/stream/global?min_id=12345
/stream/0/posts/stream/global?max_id=54321

/stream/0/posts/stream/global?since_id=12345
/stream/0/posts/stream/global?before_id=54321

If you have any questions please contact @orian or join the developer channel.

One of our goals here at App.net is to provide great documentation for our developers so they can quickly find the resources they need. We’re working on revamping our docs to be easier to navigate. In the meantime, we just put up a new starting point on our Developer Wiki for devs to get familiar with the resources available to them.

Also, a new Developer Resources page lists a growing collection of libraries, tools and other third party contributions that you can use to build great apps. We’re always looking for feedback and encourage you to add useful resources that you’ve authored or discovered.