REST users

A user represents a person with certain access permissions. Users can be local to the application or derived from a central authentication server such as LDAP. Different users can have different profile information, team assignments, group assignments, and permission settings in this product.

Note

The include_except and alone filters are available in only 5.0.03.004 and later versions of RPM. Use these filters to limit the data in API response and hence, reduce the API response time.

GET /v1/users

Returns all users.

Filters

  • keyword — String value of a user's first name, last name, login, or ID
  • email — String value of a user's email address
  • last_name — String value of a user's last name
  • first_name — String value of a user's first name
  • active — Boolean value to show active users (default is to show only active users)
  • inactive — Boolean value to show inactive users
  • root — Boolean value to show root users
  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item

Associated items

users

teams, groups

Common attributes

  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not Found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/users?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/users?token=[api_token]

Filter examples: 

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "keyword":"admin" } }' http://[rails_host]/v1/users?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"teams" }}' https://[rails_host]/v1/users?token=[api_token]

GET /v1/users/[id]

Returns a user by ID.

Common attributes

  • id — Unique numerical ID for the record
  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API token for authentication

Filters

  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item

Associated items

users

teams, groups

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when the record to show is not found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X GET http://[rails_host]/v1/users/[id]?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/users/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "include_except":"teams" }}' https://[rails_host]/v1/users/[id]?token=[api_token]

POST /v1/users

Creates a new user from posted data.

Required attributes

  • email — String email address for the user
  • first_name — String first name of the user
  • last_name — String last name of the user
  • login — String for the user login

  • password — String password of the user

    Important

    The password must contain at least 8 characters and must not have more than two similar characters consecutively. The password must also satisfy any three of the four following conditions:

    • Uppercase characters (A-Z)
    • Lowercase characters (a-z)
    • Digits (0-9)
    • Special characters (~!@#$%^&*_-+=`|\(){}[]:;"'<>,.?/)
  • password_confirmation — String password confirmation of the user

Optional attributes

  • contact_number — String contact number for the user
  • employment_type — String value for the user's type of employment (for example, permanent or contractor)
  • first_day_on_calendar — Integer (1-7) for the user's first calendar day
  • group_ids — Unique numerical value that identifies a group
  • max_allocation — Integer max allocation value for the user
  • time_zone — String value for the time zone of the user (for example, 'Central Time (US & Canada)')

Common attributes

  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API token for authentication

Filters

  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item

Associated items

users

teams, groups

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid.
  • ERROR 422 Unprocessable entity — Occurs when validation fails; objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d
'<user><first_name>Sample</first_name><last_name>User</last_name><email>user@example.com</email><login>sample_user</login><password>secret</password><password_confirmation>secret</password_confirmation><group_ids>1</group_ids></user>'
http://[rails_host]/v1/users?token=[api_token]
curl -i -H "accept: application/json" -H
"Content-type: application/json" -X POST -d '{"email":"user@example.com",
"first_name":"Sample","last_name":"User","login":"sample_user","password":"secret","password_confirmation":"secret","group_ids":1}'
http://[rails_host]/v1/users?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "user": {"email":"user@example.com","first_name":"Rest","last_name":"User","login":"sample_user","password":"secret","password_confirmation":"secret","group_ids":1}, "filters": {"include_except" : "teams"}}' https://[rails_host]/v1/users/?token=[api_token]

PUT /v1/users/[id]

Updates an existing user with values from a posted document.

Editable attributes

  • active — Boolean value with true for active users and false for inactive users
  • contact_number — String contact number for the user
  • email — String email address for the user
  • employment_type — String value for the user's type of employment (for example, permanent or contractor)
  • first_day_on_calendar — Integer (1-7) for the user's first calendar day
  • first_name — String first name of the user
  • group_ids — Unique numerical value that identifies a group
  • last_name — String last name of the user

  • login — String for the user login

    Note

    You cannot change the Login while editing a user.

  • max_allocation — Integer max allocation value for the user
  • password — String password of the user
    You must make sure that the user password must satisfy the password creation conditions.
  • password_confirmation — String password confirmation of the user
  • time_zone — String value for the time zone of the user (for example, 'Central Time (US & Canada)')

Common attributes

  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API token for authentication

Filters

  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item

Associated items

users

teams, groups

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when the record to update is not found
  • ERROR 422 Unprocessable entity — Occurs when validation fails; objects and errors are returned

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X PUT -d
'<user><email>new_email@example.com</email><group_ids>1</group_ids>’
http://[rails_host]/v1/users/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "user": { "email"
: "new_email@example.com", "group_ids":1}}'
http://[rails_host]/v1/users/[id]?token=[api_token]

Filter example:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "user": { "first_name" : "User 1", "last_name": "Renamed"}, "filters": { "include_except":"teams" }}' https://[rails_host]/v1/users/[id]?token=[api_token]

PUT /v1/users/update_profile

Updates the basic details of a user's profile, who do not have permissions to edit.

Editable attributes

  • first_name — String first name of the user 
  • last_name — String last name of the user
  • password — String password of the user
  • password_confirmation — string password confirmation of the user
  • email — String email address of the user

  • token — Your API token for authentication. 

    Note

    The user details will be updated to the current user based on the API token you passed.

  • contact_number — String contact number of the user
  • time_zone — String value, Central Time (US and Canada) for the user
  • first_day_on_calendar — integer (1-7) for calendar first day of the user
  • format — Make sure to include an accept header or add .xml or .json to the last path element

Filters

  • include_except—Comma-separated strings of the top-level associated items to exclude from the response. You can remove only top-level associated items from the response and these associated items should be a collection (zero to many) of other objects (not a simple property—string, numeric, boolean, and so on). For example, you can remove components from an application but you cannot remove route gates (it is not a top-level associated item) or app_version (it is a simple property). If you provide an incorrect associated item name (for example, the associated item does not exist, is not at the top level, or is a property), the name is ignored. See the table below for the items and their associated items.
  • alone—Boolean value to return only the item or the associated items as well along with the item. If set to false (default), item and associated item details are returned; if set to true, only item details are returned. See the table below for the items and their associated items. See the table below for the items and their associated items.

Item

Associated items

users

teams, groups

Example

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -k -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "user":{"password":"secret123","password_confirmation":"secret123"}}' https://[rails_host]/v1/users/update_profile?token=[user_api_token]

Filter example:

curl -k -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "user":{"email":"user@example.com"}, "filters": { "include_except":"teams" }}' https://[rails_host]/v1/users/update_profile?token=[user_api_token]

DELETE /v1/users/[id]

Makes a user inactive. Sets the active parameter for the user to false.

Common attributes

  • id — Unique numerical ID for the record
  • format — Be sure to include an accept header or add .xml or .json to the last path element
  • token — Your API token for authentication

Errors caused

  • ERROR 403 Forbidden — Occurs when the token is invalid
  • ERROR 404 Not found — Occurs when no records are found

Examples

To test this method, insert this URL or your valid API key and application host into a browser or HTTP client like wget or curl. For example:

curl -i -H "accept: text/xml" -X DELETE http://[rails_host]/v1/users/[id]?token=[api_token]
curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/users/[id]?token=[api_token]

Sample output

The following JSON is sample output from GET /v1/users:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "c18d8d685ef59b085d943df61965cf46"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 7ae70a72aece24779ccbe7ddf61ec756
X-Runtime: 0.627000
Content-Type: application/json;charset=utf-8
Content-Length: 1224
Date: Fri, 26 Oct 2012 07:35:25 GMT

{
     "active": true,
     "admin": false,
     "contact_number": "",
     "created_at": "2012-04-30T20:00:00-04:00",
     "email": "user_01@ex.com",
     "employment_type": "permanent",
     "first_name": "John",
     "global_access": false,
     "id": 1,
     "last_name": "Administrator",
     "location": "New York",
     "login": "admin",
     "max_allocation": 100,
     "system_user": true,
     "time_zone": "Eastern Time (US & Canada)",
     "type": null,
     "updated_at": "2015-09-24T07:51:49-04:00",
     "teams": [],
     "groups": [
         {
             "id": 20,
             "name": "Coordinator Group"
         },
         {
             "id": 30,
             "name": "Root"
         },
         {
             "id": 25,
             "name": "Coordinator Admin Group"
         },
         {
             "id": 29,
             "name": "Site Admin Group"
         }
     ]
 }

The following XML is sample output from GET /v1/users/1:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "0f6586db4a92d109410481c33dbdef2b"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: a06c84aa93782c653643149a22f941a9
X-Runtime: 0.244000
Content-Type: application/xml;charset=utf-8
Content-Length: 2973
Date: Fri, 26 Oct 2012 07:38:13 GMT

<?xml version="1.0" encoding="UTF-8"?>
<user>
  <active type="boolean">true</active>
  <admin type="boolean">false</admin>
  <contact-number></contact-number>
  <created-at type="datetime">2012-04-30T20:00:00-04:00</created-at>
  <email>user_01@ex.com</email>
  <employment-type>permanent</employment-type>
  <first-name>John</first-name>
  <global-access type="boolean">false</global-access>
  <id type="integer">1</id>
  <last-name>Administrator</last-name>
  <location>New York</location>
  <login>admin</login>
  <max-allocation type="integer">100</max-allocation>
  <system-user type="boolean">true</system-user>
  <time-zone>Eastern Time (US &amp; Canada)</time-zone>
  <type nil="true"/>
  <updated-at type="datetime">2015-09-24T05:16:00-04:00</updated-at>
  <teams type="array"/>
  <groups type="array">
    <group>
      <id type="integer">20</id>
      <name>Coordinator Group</name>
    </group>
    <group>
      <id type="integer">30</id>
      <name>Root</name>
    </group>
    <group>
      <id type="integer">25</id>
      <name>Coordinator Admin Group</name>
    </group>
    <group>
      <id type="integer">29</id>
      <name>Site Admin Group</name>
    </group>
  </groups>
</user>

Related topic

Administering users, roles, and access permissions

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*