Skip to Content
Information
Unsupported content This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.

REST teams

A team is a collection of users to which access rights for applications are assigned and permission levels set on a per environment basis. Team's access settigns can be used in conjunction with groups to mass-assign users from different groups (for example, Database Administrators, and Developers) into a team to allow access to particular applications.

GET /v1/teams

Returns all teams.

Filters

  • name — String value for the team name
  • active — Boolean value to show active teams (default is to show only active teams)
  • inactive — Boolean value to show inactive teams

Common attributes

  • format — Ensure 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/teams?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/teams?token=[api_token]

An example of filters:

curl -i -H "accept: application/json" -H "Content-type: application/json" -X GET -d '{ "filters": { "name":"Sample Team" } }' http://[rails_host]/v1/teams?token=[api_token]

GET /v1/teams/[id]

Returns a team by ID.

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure 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 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/teams/[id]?token=[api_token] 
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/teams/[id]?token=[api_token]

POST /v1/teams

Creates a new team from posted data.

Required attributes

  • name — String name of the team (must be unique)

Optional attributes

  • active — Boolean value for active (default true)
  • app_ids — Array of integer IDs for related applications
  • user_ids — Array of integer IDs for related users
  • group_ids — Array of integer IDs for related groups
  • user_id — Integer ID of the user who manages the team

Common attributes

  • format — Ensure 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 422 Unprocessable entity — Occurs when validation fails and 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 '<team><name>REST Team</name></team>' HTTP://[rails_host]/v1/teams?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{"team" : { "name":"Rest Team" } }' HTTP://[rails_host]/v1/teams/?token=[api_token]

PUT /v1/teams/[id]

Updates an existing team with values from a posted document.

Editable attributes

  • active — Boolean value for active
  • app_ids — Array of integer IDs for related apps
  • group_ids — Array of integer IDs for related groups
  • name — String value for the name of a team
  • user_id — Integer ID of the user who manages the team
  • user_ids — Array of integer IDs for related users

Common attributes

  • format — Ensure 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 record to update is not found
  • ERROR 422 Unprocessable entity — Occurs when validation fails and 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 '<team><name>Renamed Team</name></team>' http://[rails_host]/v1/teams/[id]?token=[api_token]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "team": { "name" : "Renamed Team" } }'  http://[rails_host]/v1/teams/[id]?token=[api_token]

DELETE /v1/teams/[id]

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

Common attributes

  • id — Numerical unique ID for record
  • format — Ensure 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

Sample output

The following JSON is a sample output from GET /v1/teams:

HTTP / 1.1 200 OK
Server: Apache - Coyote / 1.1
X - UA - Compatible: IE = Edge
ETag: "8dfff5dbed59ac191b216713c2c96236"
Cache - Control: max - age = 0,
private,
must - revalidate
X - Request - Id: c2ffc898652dffb6450d9100a75f07c1
X - Runtime: 0.325000
Content - Type: application / json;
charset = utf - 8
Content - Length: 1000
Date: Fri,
26 Oct 2012 14: 47: 01 GMT

[{
"active": true,
"created_at": "2011-04-29T00:13:51-04:00",
"id": 1,
"name": "AllAccess",
"updated_at": "2011-04-29T00:13:51-04:00",
"user_id": 1,
"apps": [],
"assigned_apps": [{
"id": 1
}],
"users": [{
"active": true,
"email": "admin@example.com",
"first_name": "John",
"id": 1,
"last_name": "Administrator",
"login": "admin"
}],
"groups": []
}, {
"active": true,
"created_at": "2012-10-26T10:44:39-04:00",
"id": 2,
"name": "Sample App Team",
"updated_at": "2012-10-26T10:44:39-04:00",
"user_id": 1,
"apps": [{
"id": 1,
"name": "Sample Application"
}],
"assigned_apps": [{
"id": 3
}],
"users": [{
"active": true,
"email": "admin@example.com",
"first_name": "John",
"id": 1,
"last_name": "Administrator",
"login": "admin"
}],
"groups": []
}, {
"active": true,
"created_at": "2011-04-29T00:13:51-04:00",
"id": 0,
"name": "[default]",
"updated_at": "2011-04-29T00:13:51-04:00",
"user_id": 1,
"apps": [{
"id": 0,
"name": "[default]"
}],
"assigned_apps": [{
"id": 2
}],
"users": [{
"active": true,
"email": "admin@example.com",
"first_name": "John",
"id": 1,
"last_name": "Administrator",
"login": "admin"
}],
"groups": []
}]

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

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-UA-Compatible: IE=Edge
ETag: "f0b4b6efe242cd641b29ddcd0df585ca"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: 7e5f93c448ff0d1cb456bea27e060e21
X-Runtime: 0.232000
Content-Type: application/xml;charset=utf-8
Content-Length: 874
Date: Fri, 26 Oct 2012 14:46:35 GMT

<?xml version="1.0" encoding="UTF-8"?>
<team>
 <active type="boolean">true</active>
 <created-at type="datetime">2012-10-26T10:44:39-04:00</created-at>
 <id type="integer">2</id>
 <name>Sample App Team</name>
 <updated-at type="datetime">2012-10-26T10:44:39-04:00</updated-at>
 <user-id type="integer">1</user-id>
 <apps type="array">
   <app>
     <id type="integer">1</id>
     <name>Sample Application</name>
   </app>
 </apps>
 <assigned-apps type="array">
   <assigned-app>
     <id type="integer">3</id>
   </assigned-app>
 </assigned-apps>
 <users type="array">
   <user>
     <active type="boolean">true</active>
     <email>admin@example.com</email>
     <first-name>John</first-name>
     <id type="integer">1</id>
     <last-name>Administrator</last-name>
     <login>admin</login>
   </user>
 </users>
 <groups type="array"/>
</team>

Related topic

Administering-users-roles-and-access-permissions

 

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

BMC Release Process Management 4.3