Difference between revisions of "REST API:role Resource"

Revision as of 19:20, 25 April 2014

Performs actions on Role records via the REST API

Requirements

You need to understand Global vs. Individual Role Assignments

Access Permissions

Users that have the Access Control permission can use this resource.

Get a Role Record

Identifies and retrieves a single Role record

Method: GET

URI: https://{yourDomain}/networking/rest/role/{recordId}

Response: <syntaxhighlight lang="xml" enclose="div">

   <id>1</id>
   <name>System Administrator</name>
   <description>System Generated Role</description>
   <ip_addr_range/>
   <date_created>2010-11-12T13:14:15Z</date_created>
   <created_id type="USER" 
     uri="https://{yourDomain}/networking/rest/user/3" 
     displayValue=" System">3</created_id>
   <date_modified>2010-11-12T13:14:15Z</date_modified>
   <modified_id type="USER" 
     uri="https://{yourDomain}/networking/rest/user/3" 
     displayValue=" System">3</modified_id>
   <users>
     <id>479771292</id>
     <user_id type="USER" 
       uri="https://{yourDomain}/networking/rest/user/1424089492" 
       displayValue="Dev User">1424089492</user_id>
     <team_id type="TEAM" 
       uri="https://{yourDomain}/networking/rest/team/1" 
       displayValue="Dev Team">1</team_id>
   </users>

   <users>
     <id>568445387</id>
     <user_id type="USER" 
       uri="https://{yourDomain}/networking/rest/user/16016a880c064ad1ba92115424851462" 
       displayValue="QA User">16016a880c064ad1ba92115424851462</user_id>
     <team_id type="TEAM" 
       uri="https://{yourDomain}/networking/rest/team/888961917" 
       displayValue="QA Team">888961917</team_id>
   </users>
  
   <team_level_record_access_permission>
      <object_id type="ObjectA" uri="" displayValue="ObjectA">ObjectA</object_id>
      <view_capability>true</view_capability>
      <update_capability>true</update_capability>
      <delete_capability>true</delete_capability>
   </team_level_record_access_permission>   
     ...

   <self_record_access_permission>
      <object_id type="ObjectA" uri="" displayValue="ObjectA">ObjectA</object_id>
      <create_capability>true</create_capability>
      <owner_delete_capability>true</owner_delete_capability>
   </self_record_access_permission>        
     ...

</role>

   0
   <description>Success</description>

</message> </platform> </syntaxhighlight>

See also: REST API:Error Codes

Dynamic Search

Search for Role records, specifying the fields to retrieve, number of records, offset, sort column, sort order, criteria

Method: GET

URI

https://{yourDomain}/networking/rest/role?{query_parameters}

Sample Search: ?fieldList=name,id & filter=name contains 'smith' & sortby='id'; (Field names are in the Fields section.)

Query Parameters

fieldList - A comma-separated list of field names to retrieve

The asterisk (*) wildcard specifies all fields
{fieldname} specifies an individual field (e.g. name)

(Use the REST API:field Resource to get a complete list of fields.)

For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
alias.* specifies all fields in the aliased object.

filter - Filtering criteria to filter the records

For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

pageSize - Number of records to retrieve from the result set in order to make a "page".
page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

getTotalRecordCount returns the number of total records.
Causes the following structure to be returned, where N is the total number of records:

  <status>
  <packageDeploy>
  ...
  </packageDeploy>
  </status>
  <message>
     0
     <description>Success</description>
  </message>

  <totalRecordCount>N</totalRecordCount>

</platform> </syntaxhighlight>

sortBy - Field name for primary sort
Ex: &sortBy=name
sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
Ex: &sortOrder=desc
sortBy2 - Field name for secondary sort
sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs

Response: <syntaxhighlight lang="xml" enclose="div">

   <record>
       <id>1</id>
       <created_id type="" 
         uri="https://{yourDomain}/networking/rest/user/3" 
         displayValue=" System">3</created_id>
       <record_locator>System Administrator</record_locator>
       <modified_id type="" 
         uri="https://{yourDomain}/networking/rest/user/3" 
         displayValue=" System">3</modified_id>
       <date_modified>2010-11-12T13:14:15Z</date_modified>
       <name>System Administrator</name>
       <date_created>2010-11-12T13:14:15Z</date_created>
   </record>

   <record>
       <id>2</id>
       <created_id type="" 
         uri="https://{yourDomain}/networking/rest/user/3" 
         displayValue=" System">3</created_id>
       <record_locator>Sales Manager</record_locator>
       <modified_id type="" 
         uri="https://{yourDomain}/networking/rest/user/3" 
         displayValue=" System">3</modified_id>
       <date_modified>2010-11-12T13:14:15Z</date_modified>
       <name>Sales Manager</name>
       <date_created>2010-11-12T13:14:15Z</date_created>
   </record>

   <record>
       <id>3</id>
       <created_id type="" 
         uri="https://{yourDomain}/networking/rest/user/3" 
         displayValue=" System">3</created_id>
       <record_locator>Sales Rep</record_locator>
       <modified_id type="" 
         uri="https://{yourDomain}/networking/rest/user/3" 
         displayValue=" System">3</modified_id>
       <date_modified>2010-11-12T13:14:15Z</date_modified>
       <name>Sales Rep</name>
       <date_created>2010-11-12T13:14:15Z</date_created>
   </record>

   <message>
       0
       <description>Success</description>
   </message>
   <recordCount>3</recordCount>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Add a Role Record

Add a Role record

Method: POST
URI: https://{yourDomain}/networking/rest/role
Request: <syntaxhighlight lang="xml" enclose="div">

   <name>Manager</name>

   <team_level_record_access_permission>
       <object_id type="ObjectA" 
         uri="" 
         displayValue="ObjectA">ObjectA</object_id>
       <view_capability>true</view_capability>
       <update_capability>true</update_capability>
       <delete_capability>true</delete_capability>
   </team_level_record_access_permission>
     ...
 
   <self_record_access_permission>
       <object_id type="ObjectB" 
         uri="" 
         displayValue="ObjectB">ObjectB</object_id>
       <create_capability>true</create_capability>
       <owner_delete_capability>true</owner_delete_capability>
   </self_record_access_permission>
     ...

</role> </platform> </syntaxhighlight>

Response: <syntaxhighlight lang="xml" enclose="div">

   <message>
       0
       <description>Success</description>
       <id>1818437421</id>      // id of the role that is just been added
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Update a Role Record

Update a Role record

Method: PUT
URI: https://{yourDomain}/networking/rest/role/{recordId}
Request: <syntaxhighlight lang="xml" enclose="div">

   <name>Team Member</name>    
    
   <team_level_record_access_permission>
      <object_id type="ObjectA" uri="" displayValue="ObjectA">ObjectA</object_id>
      <view_capability>true</view_capability>
      <update_capability>true</update_capability>
      <delete_capability>false</delete_capability>
   </team_level_record_access_permission>

</role> </platform> </syntaxhighlight>

Response: <syntaxhighlight lang="xml" enclose="div">

   <message>
       0
       <description>Success</description>
       <id>12345678</id>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Delete a Role Record

Delete a Role record

Method: DELETE
URI: https://{yourDomain}/networking/rest/role/{recordId}
Response: <syntaxhighlight lang="xml" enclose="div">

   <message>
       0
       <description>Success</description>        
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Fields

Field Name	Type	Attribute	Description	Additional Information
id	String	Read Only	Record Identifier
record_locator	String	Editable on Add/Update	Record-access index
name	String	Editable on Add/Update	Role Name
description	String	Editable on Add/Update	Role description
ip_addr_range				Login IP Address Restrictions
date_created	Date	Read Only		UTC Format
created_id	Lookup	Read Only		User ID
date_modified	Date	Read Only		UTC Format
modified_id	Lookup	Read Only		User ID

Users Tag

Tag	Field	Type	Attribute	Description
users		Tag	Read Only	Users attached to this Role
	id	String	Read Only	Record Id
	user_id	Lookup	Read Only	User ID
	team_id	Lookup	Read Only	Team ID

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools

Difference between revisions of "REST API:role Resource"

Revision as of 19:20, 25 April 2014

Contents

Requirements

Access Permissions

Get a Role Record

Dynamic Search

Add a Role Record

Update a Role Record

Delete a Role Record

Fields

Users Tag