Users

Users describes the 2cloud account of a registered user. There should only ever be one User object per physical person.

The User Resource

The User resource is represented in responses under the users property. The users property will be an array of Users.

Users appear as follows:

{
  "id": string,
  "username": string,
  "email": string,
  "email_unconfirmed": bool,
  "secret": string,
  "joined": datetime,
  "name": {
             "given": string,
             "family": string
  },
  "last_active": datetime,
  "admin": bool,
  "to_be_welcomed": bool
}

The properties are as follows:

• id: A unique, immutable identifier for this user.
• username: A memorable, user-chosen identifier. This is not guaranteed to persist over time.
• email: The email address the user would like to receive important announcements at.
• email_unconfirmed: True if the email address still needs to be confirmed, False or omitted if the address no longer needs to be confirmed.
• secret: An authentication token used as a password to access this account.
• joined: The timestamp the user registered their account, expressed according to RFC 3339.
• name: A JSON object containing the following properties:
  • given: The given or first name of the user.
  • family: the family or last name of the user.
• last_active: The date and time a user last was observed to be actively engaging with the service, expressed according to RFC 3339.
• admin: True if the user has administrative access on this server, False or omitted if the user does not.
• to_be_welcomed: True if the user has not received an email welcoming them to the service yet, False or omitted if they have.

Listing Users

This request requires administrative credentials. It will reply with a 403 error if the authorising user does not have administrative access to the server.

Request Format

Endpoint

GET /users

Optional Headers

• If-Modified-Since: Displays only users registered after the specified date. Date should be specified according to RFC 3339. For example: Sat, 29 Oct 1994 19:43:31 GMT

Parameters

The following parameters are accepted as query parameters:

NOTE: TODO

Response Format

Header

This request sets the Last-Modified header to the latest last_active property of the Users returned.

The Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.

Body

This request returns a list of user resources as a JSON array:

{
  "code": 200,
  "msg": "Successfully retrieved a list of users",
  "users": [
    {
      // See the User Resource for the contents of this part
    },
    {
      // See the User Resource for the contents of this part
    }
  ]
}

In the event no users are to be returned (none matched the filter combination of the query parameters and the If-Modified-Since header), an empty array will be returned.

Getting Information About A User

This request requires only authentication if it is run against the profile of the authenticating user. If it is run against another user's profile, it requires administrative credentials.

Request Format

Endpoint

GET /users/{username}

Optional Parameters

The following parameters can be specified in the URL:

• include_subscription: If set to 1, the response will also include the information about this user's subscription.

Response Format

Header

This request sets the Last-Modified header to the last_active property of the User returned.

If include_subscription is not set, the Content-Type of this request will be users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be users/json.

If include_subscription is set, the Content-Type of this request will be mixed:subscriptions,users/encoding. For example, when returned in JSON encoding (the only option available in version 1), the content-Type will mixed:subscriptions,users/json.

Body

This request returns a list of user resources as a JSON array. The array will only have one item:

{
  "code": 200,
  "msg": "Successfully retrieved a list of users",
  "users": [
    {
      // See the User Resource for the contents of this part
    }
  ]
}

If the include_subscription parameter is set, there will also be a subscriptions property in the response. It will hold an array, which will contain a single Subscription Resource.

{
  "code": 200,
  "msg": "Successfully retrieved a list of users",
  "users": [
    {
      // See the User Resource for the contents of this part
    }
  ],
  "subscriptions": [
    {
      // See the Subscription Resource for the contents of this part
    }
  ]
}

Associating A User With An Account

Updating A User's Information

Deleting A User