Skip to content
This repository was archived by the owner on Feb 24, 2020. It is now read-only.

Users

Jump to bottom
Paddy Foran edited this page Oct 31, 2012 · 15 revisions

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
}

Mutable Properties

Mutable properties are properties that can be modified through interactions with the API.

  • 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.
  • 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.
  • 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.

Immutable Properties

Immutable properties are properties that are created and modified only by the system; there is no way to modify them through the API.

  • id: A unique, immutable identifier for this user.
  • 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.
  • last_active: The date and time a user last was observed to be actively engaging with the service, expressed according to RFC 3339.

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 Parameters

The following URL parameters are accepted when listing Users, and will filter the list accordingly:

  • active_after: the lower bound on when a User was last active. This should be specified as a URL-encoded ISO 8601 timestamp. Only Users active after the specified date will be returned.
  • active_before: the upper bound on when a User was last active. This should be specified as a URL-encoded ISO 8601 timestamp. Only Users active before the specified date will be returned.
  • joined_after: the lower bound on when a User registered. This should be specified as a URL-encoded ISO 8601 timestamp. Only Users who joined after the specified date will be returned.
  • joined_before: the upper bound on when a User registered. This should be specified as a URL-encoded ISO 8601 timestamp. Only Users who joined before the specified date will be returned.
  • count: the maximum number of Users to return, as an integer. Defaults to 20, with a maximum of 100.
  • to_be_welcomed: If set to 1, only Users who still need to be welcomed will be returned. If set to 0, only Users who have been welcomed will be returned.
  • email_unconfirmed: If set to 1, only Users whose email_unconfirmed property is set to True will be returned. If set to 0, only Users whose email_unconfirmed property is set to False will be returned.

Result Ordering

Results will be ordered depending on the parameters that are specified. If more than one group of parameters is specified, whatever is lower in the below list will take precedence.

  • If no parameters, joined_after, or joined_before is specified, the results will be ordered by the User's joined property, descending.
  • If active_after or active_before is specified, the results will be ordered by the User's last_active property, descending.

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 user information",
  "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 user information",
  "users": [
    {
      // See the User Resource for the contents of this part
    }
  ],
  "subscriptions": [
    {
      // See the Subscription Resource for the contents of this part
    }
  ]
}

Creating A New User

Before a User can be created, an Account must be created to associate with the User. See the Accounts documentation for information on creating an Account.

Request Format

Endpoint

POST /users

Request Headers

Because this request occurs before the User has credentials, neither the From nor the Authorization headers need to be set, unless an administrator is registering an account on behalf of another user. The User-Agent, Content-Type, and Content-Length headers, however, need to be set.

Request Body

The request body should be a User Resource and an Account Resource.

In the User Resource, only the Mutable Properties will be used; the rest will be ignored. Furthermore, the admin and to_be_welcomed properties will only be used if the request is authorised by a User with admin credentials. Otherwise, they will be ignored.

In the Account Resource, only the ID property will be used; the rest will be ignored.

A sample request body:

{
  "user": {
  	"username": "myusername",
  	"email": "my@email.com",
  	"name": {
  		"given": "Test",
  		"family": "User"
  	}
  },
  "account": {
  	"id": "someaccountIDgoeshere"
  }
}

Response Format

Header

This request sets the Last-Modified header to the last_active property of the User 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. The array will only have one item—the User that was created:

{
  "code": 201,
  "msg": "Successfully created a user account",
  "users": [
    {
      // See the User Resource for the contents of this part
    }
  ]
}

Updating A User's Information

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

PUT /users/{username}

Request Headers

Because this request has a body, the Content-Type, and Content-Length headers need to be set.

Request Body

The request body should be a User Resource.

In the User Resource, only the Mutable Properties will be used; the rest will be ignored. Furthermore, the admin and to_be_welcomed properties will only be used if the request is authorised by a User with admin credentials. Otherwise, they will be ignored. Finally, the username property cannot be modified in this request.

A sample request body:

{
  "user": {
  	"email": "my@email.com",
  	"name": {
  		"given": "Test",
  		"family": "User"
  	}
  }
}

Response Format

Header

This request sets the Last-Modified header to the last_active property of the User 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. The array will only have one item—the User that was modified:

{
  "code": 200,
  "msg": "Successfully updated the user account",
  "users": [
    {
      // See the User Resource for the contents of this part
    }
  ]
}

Deleting 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

DELETE /users/{username}

Response Format

Header

This request sets the Last-Modified header to the last_active property of the User 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. The array will only have one item—the User that was just deleted:

{
  "code": 200,
  "msg": "Successfully deleted the user",
  "users": [
    {
      // See the User Resource for the contents of this part
    }
  ]
}
Clone this wiki locally