General endpoints: account registration and settings

GET /account

Retrieves account information for the account associated to the access token provided.

• requires access token
• scope: OAuthScope.USER_EXTENDED

The account object is represented as:

@JsonProperty("id")
public final String externalID; // the external ID is unique for each app.

@JsonProperty("email")
public final String email;

@JsonProperty("tz")
public final Integer tzOffsetMillis;

@JsonProperty("name")
public final String name;

@JsonProperty("gender")
public final Gender gender;

@JsonProperty("height")
public final Integer height;

@JsonProperty("weight")
public final Integer weight;

@JsonProperty("dob")
public final DateTime DOB;

@JsonProperty("email_verified")
public final DateTime DOB;

Gender is an enum with the following values:

public enum Gender {

    FEMALE(0),
    MALE(1),
    OTHER(2);
}

Raw request:

curl -i https://dev-api.hello.is/v1/account -H 'Authorization : Bearer 1.abc297c53c8f48e69850ef9397ee2c0d'
HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 30 Jul 2014 04:05:54 GMT
Content-Length: 100
Connection: keep-alive

{"email":"[email protected]","name":"tim bart","gender":"OTHER","height":0,"weight":0,"id":"","tz":0, "email_verified":false}

Notes:

• missing from the current implementation is the notion of age or date of birth
• the timezone tz field represents the timezone offset from GMT in milliseconds

POST /account?sig=xxxxxx

Creates an account through a registration.

• DOES NOT REQUIRE access token
• requires a signature passed a a query parameter.

Registration class:

public class Registration {

    @JsonProperty("name")
    public final String name;

    @JsonProperty("email")
    public final String email;

    @JsonProperty("password")
    public final String password;

    @JsonProperty("gender")
    public final Gender gender;

    @JsonProperty("height")
    public final Integer height;

    @JsonProperty("weight")
    public final Integer weight;

    @JsonProperty("tz")
    public final Integer tzOffsetMillis;

    @JsonProperty("dob")
    public final DateTime age;
}

Raw request:

curl -i -X POST -d '{"password" : "my password", "email" : "[email protected]", "name" : "new name", "tz" : -252000}' 'http://api.skeletor.com/account?sig=xxx' -H 'Content-type : application/json

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 30 Jul 2014 04:49:41 GMT
Content-Length: 149
Connection: keep-alive

{"email":"[email protected]","name":"new name","gender":"OTHER","height":null,"weight":null,"id":"a2f149ebdb31db21c66454e16de02504","tz":-252000}

Should the account already exist a HTTP 409 will be returned.

HTTP/1.1 409 Conflict
Content-Type: application/json
Date: Wed, 30 Jul 2014 04:48:50 GMT
Content-Length: 48
Connection: keep-alive

{"code":409,"message":"Account already exists."}

If IP address is ratelimited a HTTP 429 will be returned.

HTTP/1.1 429 Too many requests
Content-Type: application/json
Date: Wed, 30 Jul 2014 04:48:50 GMT
Content-Length: 48
Connection: keep-alive

{"code":429,"message":"Too many requests"}

Notes:

• set dob, height, weight to 0/nukk if these fields are optional.
• the timezone tz field represents the timezone offset from GMT in milliseconds
• if gender is null, Gender.OTHER will be used.
• Restrictions on password length or common words haven’t been implemented yet. They will be in the future.
• the signature query param is not yet enforced. Clients and server will have to agree on a signature scheme.

PUT /account

Updates the account information. Password update is handled separately. The following json is expected.

{
  "height" : 185,
  "weight" : 150,
  "tz" : 3600000,
  "gender" : "OTHER",
  "name" : "tim bart",
  "dob" : "2014-06-26",
  "last_modified" : 1409861723884
}

The last_modified is required to guarantee atomic updates (CAS style). If the last_modified doesn’t match the one stored in DB, an HTTP 412 response will be returned.

{"code":412,"message":"pre condition failed"}

POST /account/email

Updates the account email. For convenience, we expect the full account, but only email and last_modified are effectively used.

• requires access token
• scope: OAuthScope.USER_EXTENDED

Notes: updating the email address invalidates previous email validation. email_verified should always be null after an email address update.

The following json is expected.

{
  "email" : "[email protected]",
  "height" : 185,
  "weight" : 150,
  "tz" : 3600000,
  "gender" : "OTHER",
  "name" : "tim bart",
  "dob" : "2014-06-26",
  "last_modified" : 1409861723884
}

The last_modified is required to guarantee atomic updates (CAS style). If the last_modified doesn’t match the one stored in DB.

Response: HTTP 200 with the updated account.

POST /account/password

Updates the account password.

• requires access token
• scope: OAuthScope.USER_EXTENDED

The following json is expected:

{
  "current_password" : "my current password",
  "new_password" : "my new password"
}

Response: HTTP 204 if updated successfully or HTTP 409 if conflict.

Note: last modified is not required since only the password is updated and it requires the current password.