Skip to Content

REST teams

A team is a collection of users to which access rights for applications are assigned and permission levels are set for each environment. A team's access settings 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 — 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/teams?token=[api_token]
curl -i -H "accept: application/json" -X GET http://[rails_host]/v1/teams?token=[api_token]

The following example shows 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 — Unique numerical ID for 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 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
  • group_ids — Array of integer IDs for related groups
  • role-environment-mappings — Array of integer IDs of a related group, application, environment and role in a team

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 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 '<team><name>REST Team</name></team>' HTTP://[rails_host]/v1/teams?token=[api_token]
curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X POST -d '<team><name>Name Team</name><group_ids>2</group_ids> <app_ids>1</app_ids><role-environment-mappings type="array"><role-environment-mapping><group-id type="integer">16</group-id><app-id type="integer">2</app-id><environment-id type="integer">3</environment-id><role-id type="integer">13</role-id></role-environment-mapping></role-environment-mappings></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]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X POST -d '{ "team": { "name": "New Team", "group_ids":1, "app_ids":1,
"role_environment_mappings": [{ "group-id ":1, "app-id":1, "environment-id":14, "role-id":2}]}}' 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
  • role-environment-mappings — Array of integer IDs of a related group, application, environment and role in a team

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 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 '<team><name>Renamed Team</name></team>' http://[rails_host]/v1/teams/[id]?token=[api_token]
curl -i -H "accept: text/xml" -H "Content-type: text/xml" -X PUT -d '<team><name>Renamed Team</name><group_ids>2</group_ids> <app_ids>1</app_ids><role-environment-mappings type="array"><role-environment-mapping><group-id type="integer">16</group-id><app-id type="integer">2</app-id><environment-id
type="integer">3</environment-id><role-id type="integer">13</role-id></role-environment-mapping></role-environment-mappings></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]
curl -i -H "accept: application/json" -H "Content-type: application/json" -X PUT -d '{ "team": { "name": "Edit Team", "group_ids":1,
"app_ids":1, "role_environment_mappings": [{ "group-id ":1, "app-id":1, "environment-id":14, "role-id":2}]}}' 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 — 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/teams/[id]?token=[api_token]
  curl -i -H "accept: application/json" -X DELETE http://[rails_host]/v1/teams/[id]?token=[api_token]

 

Sample output

The following JSON is 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 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.8