API v2 -> v3 Migration Guide

Although version 3 of the API is an entire rewrite, for most of the API routes, there is very little you have to change. For an in-depth overview, read this.

For a real life example, I upgraded my Node API wrapper to use v3 of the API.

Step 1

The most obvious change is make your base URL https://habitica.com/api/v3/ instead of https://habitica.com/api/v2/.

// Old
var BASE_URL = 'https://habitica.com/api/v2/'  
// New
var BASE_URL = 'https://habitica.com/api/v3/'  

Step 2

Many of the route urls stayed exactly the same, but a few changed. Most notably, almost all the /user/tasks routes changed to /tasks.

Note: One exception to the above statement is if you want to get all of your user's tasks, you can use the GET /tasks/user route.

See the API v2 docs and compare them to the API v3 docs for other changes.

// Old
var userTaskUrl = BASE_URL + 'user/tasks';

// New
var userTaskUrl = BASE_URL + 'tasks/user'  

Step 3

The result of a successful request will contain a data property with the information returned from the request. In most cases, this data will be exactly the same as the data returned from version 2 of the API. So, in most cases, all you need to do is grab the data from the data property.

// Old
request.get(userTaskUrl, (err, response) => {  
  response; // an array of tasks
});

// New
request.get(userTaskUrl, (err, response) => {  
  response.data; // an array of tasks
});

Step 4

The result of an unsuccessful request will contain an error property indicating the type of error and a message property translated into your user's specified language that you can display to the user.

// Old
request.get(userTaskUrl, (err, response) => {  
  if (err) {
    // unpredictable format, different for many routes
    console.error(err); 
  }
});

// New
request.get(userTaskUrl, (err, response) => {  
  if (err) {
    // A translated message about the error 
    // that you can display to your user
    console.error(err.message); 
  }
});

Step 5

Share your integration with us in the Aspiring Comrades Guild!