API v2

#API v2 Key difference from old API is that you can't edit objects. Instead you can change object properties (only if they are strings or numbers!).

###Where and how to send request?

URL: https://habitrpg.com/api/v2

Headers:

• x-api-user: your user ID
• x-api-key: your API key

Request Method:POST Content-Type:application/json

For example:

curl --compressed --header "Content-Type:application/json" \
--header 'x-api-user: 31ffa28c-2519-47ee-92a8-6e736660b446' \
--header 'x-api-key: a01a63d2-8b5b-4756-a863-9e2a344580f8' \
--data {} \
http://localhost:3000/api/v2

This shall return full user object.

###API:

####Get user object:

To get user object you have to POST an empty json object {}. As you noticed this is not REST API. Reason is that we are not actually invoking API calls, instead we are syncronising actions from client to server and getting user model in response.

In response to each valid set of actions server will send fully blown user object. An empty action {} is a valid action.

###Actions:

Types of actions you can submit described below. You can combine them and send together in a JSON array like [{},{},{}] They will be applied to the model in order of submission. Response from the server will reflect latest changes. Keep in mind thath response from server might include some unrequested changes. They might have been done from other\desktop client or computed by server due to 24 hour daily cycle. That is why server always replies with full user object.

####Add task

{op:'addTask', task:taskObj} Where taskObj is for example

{
    "id": "eaefa01d-d502-4645-b7a7-4582bfbdab55",
    "type": "habit",
    "up": true,
    "down": true,
    "text": "Hello!",    
    "value": 1        
}

You must generate ID on the client and you must indicate task type, i.e. habit, todo, reward,daily. Other fields are speciefic to each task type. You can look at the returned user object in previous step to get an idea what fields each task type has.

####Delete task

{op:'delTask', task:taskObj}

Use this action to delete task. taskObj must have type and id properties defined. I.e. {type:"habit",id:'4002ed12-1e95-4d5b-be90-b943881515e7'}.

####Sort task

{op:'sortTask',task:taskObj,from:INT,to:INT}

To sort task list.

from is an index of element moved before it was moved. to is a new index of the element.

####Generic set method {op:'set',path:'', value:''} You can use this action in case you need to set one of the existing properties of the user object. This action will only work if property you are trying to change is string or number. It will do nothing if you point it to nonexisting or object property.

Value can be either string or number. Value can't be {}

Path is a string to be resolved on server in the scope of server's user object. That is same as user returned by API except for tasks!.

All tasks shall be accesed by ID using tasks.taskID path, i.e.:

{op: 'set', path: "tasks.4002ed12-1e95-4d5b-be90-b943881515e7.notes", value: 'My notes'}.

Other fields in user object map 1 to 1 with the user returned from API i.e.:

{op: 'set', path: "preferences.hair", value: 'black'}.

Note, this is all subject to change. The API is not perfect, and should be used with caution. Please let us know if you have any issues.