Difference between revisions of "REST API:record Resource"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
 
(53 intermediate revisions by the same user not shown)
Line 1: Line 1:
Access Record information via the [[REST API]] (Retrieve, Add, Update, Delete, Search)
Manage [[Object]] records using the [[REST API]].
 
:''See also:''
::* The REST [[REST API:bulk record Resource|bulk record]] resource to work with multiple records at one time.
::* The REST [[REST API:composite record Resource|composite record]] resource to work with a record and related records in other objects.


=== About the Record Resource ===
=== About the Record Resource ===
Line 5: Line 9:
==== Available Objects ====
==== Available Objects ====
:These objects are available in the record Resource
:These objects are available in the record Resource
:*[[Built-in Objects]] (except those deprecated, below)
::*{{Type}}s (except the special {{Type}}s, listed below)
:*[[CRM Objects]]
::*{{Type|}}s
:*{{Type|}}s
:*[[Project Task]]s
:*[[Project Phase]]s


:For each object, it is possible to access and/or manage:
==== Predefined Custom Object Fields====
:*[[Workflows#Records, States, Actions, and Owners|Workflow State and Owners]]
:Every [[Custom Object]] is created with a number of fields that are automatically modified for each record.
 
==== Retrieve Record Permissions Query Parameter ====
:When retrieving a record or doing a search, it is possible to retrieve the user's record permissions with respect to those records, as well as the data. That capability is useful, for example, when an application needs to determine whether or not to display [Edit] and [Delete] buttons.
 
:To specify the parameter, put <tt>retrieveRecordPermissions=true</tt> into the query string for the resource. For example:
:{|
<pre>https://{domain}/networking/rest/record/{objectName}/{record_id}?retrieveRecordPermissions=true
https://{domain}/networking/rest/record/{objectName}/{search_parameters}&retrieveRecordPermissions=true
</pre>
|}
:When specified, and when the field list contains the <tt>id</tt> field (needed to do an update or delete), the returned data tells which operations the user has permission to do:
:<syntaxhighlight lang="xml" enclose="div">
      ...
    <recordPermissions>
        <canUpdate>true</canUpdate>
        <canDelete>false</canDelete>
    </recordPermissions>
</record>
</syntaxhighlight>
 
:''Learn more:''
:* [[Specifying Query Parameters in REST APIs]]
:* [[#Retrieve a Record|Retrieve a Record]]
:* [[#Dynamic Search|Dynamic Search]]


==== Predefined Custom Object Fields====
:''Learn more:'' [[Custom Object#Predefined Fields]]
:Every [[Custom Object]] is created with a number of fields that are automically modified for each record.


:''Learn More:'' [[Custom Object#Predefined Fields]]
==== Data Format for Different Field Types ====
:When adding and updating records, the field type determines the data format.
:''Learn more:'' [[REST API:Field Type Reference]]


==== Deprecated Objects ====
====Special Considerations for Enumerated Fields====
:These [[Built-in Objects]] can no longer be retrieved using the record Resource. (They have specific resource URLs, instead):
:When a record contains [[Enumerated Fields]], there are additional factors to take into account.
:*[[USER]] - use the [[REST_API:user _Resource|user Resource]]
:''Learn more:'' [[Enumerated Field Behavior For REST Web Services]]
:*[[ROLE]] - use the [[REST_API:role_Resource|role Resource]]
:*[[TEAM]] - use the [[REST_API:team_Resource|team Resource]]
:*[[USER TEAM]] use the [[REST_API:userTeam_Resource|userTeam Resource]]


==== Deprecated Fields ====
==== Special {{Typenolink}}s ====
:* <tt>workflow_owner</tt> - This field has been deprecated for GETs. It is still present and can be used for updates, but it no longer contains any data when returned. Use this resource, instead: [[#Identify_Workflow_Owners|Identify_Workflow_Owners]].
:These {{Type}}s can not be retrieved using the record Resource. They have specific resource URLs, instead:
:* User - use the [[REST_API:user_Resource|user Resource]]
:* Role - use the [[REST_API:role_Resource|role Resource]]
:* Team - use the [[REST_API:team_Resource|team Resource]]
:* USER_TEAM use the [[REST_API:userTeam_Resource|userTeam Resource]]


==== Requirements ====
==== Requirements ====
Line 62: Line 41:
;Method:GET
;Method:GET
;URI:
;URI:
:<tt><nowiki>https://{domain}/networking/rest/record/{objectName}/{recordId}</nowiki></tt>
:<tt>{{platformURL}}/rest/record/{objectName}/{recordId}</tt>
:<tt><nowiki>https://{domain}/networking/rest/record/{objectName}/{recordId}?retrieveRecordPermissions=true</nowiki></tt>
:<tt>{{platformURL}}/rest/record/{objectName}/{recordId}?retrieveRecordPermissions=true</tt>


:where the optional [[#Retrieve Record Permissions Query Parameter|Retrieve Record Permissions Query Parameter]] adds extra data that tells whether the user has add or delete capabilities.
:where the optional [[REST API:Retrieve Record Permissions Query Parameter|Retrieve Record Permissions Query Parameter]] adds extra data that tells whether the user has add or delete capabilities.


;Response:
;Response:
Line 71: Line 50:
<platform>
<platform>
   <record>
   <record>
     <field1>...</field1>
     <field1>...value...</field1>
     <field2>...</field2>
     <field2>...value...</field2>
    <field3 displayValue="...">...value...</field3>
         …
         …
   </record>
   </record>
Line 78: Line 58:
</syntaxhighlight>
</syntaxhighlight>
:'''Notes:'''
:'''Notes:'''
:* An enumerated field returns the field label in the <tt>displayValue</tt> attribute. The field value is returned as the data inside the tag.
:* A [[Multi Object Lookup]] field has two attributes, in addition to the <tt>type</tt> attribute that is specified when you do an add or update. The syntax looks like this:
:* A [[Multi Object Lookup]] field has two attributes, in addition to the <tt>type</tt> attribute that is specified when you do an add or update. The syntax looks like this:
::<syntaxhighlight lang="java" enclose="div">
::<syntaxhighlight lang="java" enclose="div">
Line 88: Line 69:
::<syntaxhighlight lang="java" enclose="div">
::<syntaxhighlight lang="java" enclose="div">
<tag type="Priority_Tag"  
<tag type="Priority_Tag"  
     uri="https://{domain}/networking/rest/record/Priority_Tag/9467890"  
     uri="https://{{domain}}/networking/rest/record/Priority_Tag/9467890"  
     displayValue="Rush, Overnight">9467890</tag>
     displayValue="Rush, Overnight">9467890</tag>
</syntaxhighlight>
</syntaxhighlight>
<!--
===Retrieve all Records in an Object, based on a View===
Identifies and retrieves all records in an [[Object]], based on a [[View]]
;Method:GET
;URI:<tt><nowiki>https://{domain}/networking/rest/record/view/{viewId}</nowiki></tt>
;Response:
Records in the view
:<syntaxhighlight lang="xml" enclose="div">
<platform>
    <fieldMetaData>
        <field>
            <id>1000imq1932721702</id>
            <objectId>1000ilr1011276656</objectId>
            <title>Department</title>
            <type>TEXT_FIELD</type>
            <isStandard>false</isStandard>
            <tableColumn>department</tableColumn>
            <isTracked>false</isTracked>
            <isSignField>false</isSignField>
            <universalProperty>false</universalProperty>
            <date_created>2010-11-12T13:14:15Z</date_created>
            <date_modified>2010-11-12T13:14:15Z</date_modified>
            <created_id type=""
                uri="https://server/networking/rest/USER/'487b72b3cd274f97bd4cf5d3dfa45d95"
                displayValue="Demo MSP">487b72b3cd274f97bd4cf5d3dfa45d95</created_id>
            <modified_id type=""
                  uri="https://server/networking/rest/USER/487b72b3cd274f97bd4cf5d3dfa45d95"
                displayValue="Demo MSP">487b72b3cd274f97bd4cf5d3dfa45d95</modified_id>
            <displayLength>30</displayLength>
            <description/>
            <flagInactive>false</flagInactive>
            <maxStorageLength>50</maxStorageLength>
        </field>
       
          ........
    </fieldMetaDataBean>
    <record>
        <field1>
        <field2>
            ....
    </record>
            ....
   
    <recordCount>30</recordCount>
    <message>
          <code>0</code>
          <description>Success</description>
    </message>
</platform>
</syntaxhighlight>-->


===Dynamic Search===
===Dynamic Search===
;Method:GET
;Method:GET


;URI:<tt><nowiki>https://{domain}/networking/rest/record/{objectName}?{query_params}&retrieveRecordPermissions=true</nowiki></tt>
;URI:
 
:<tt>{{platformURL}}/rest/record/{objectName}?{query_params}</tt>
:<tt>{{platformURL}}/rest/record/{objectName}?{query_params}&retrieveRecordPermissions=true</tt>
:where:
:where:
::* <tt>{objectName}</tt> is an [[Object Type Identifier]] or [[Database View | Database View ID]]
::* <tt>{objectName}</tt> is an [[Object Type Identifier]] or [[Database View | Database View ID]]
::* The optional [[#Retrieve Record Permissions Query Parameter|Retrieve Record Permissions Query Parameter]] adds extra data that tells whether the user has add or delete capabilities. For example:
::* The optional [[REST API:Retrieve Record Permissions Query Parameter|Retrieve Record Permissions Query Parameter]] adds extra data that tells whether the user has add or delete capabilities.  
:::<syntaxhighlight lang="xml" enclose="div">
<recordPermissions>
    <canUpdate>true</canUpdate>
    <canDelete>true</canDelete>
</recordPermissions>
</syntaxhighlight>


:;Sample Search:
:;Sample Search:
:: <tt><nowiki>?fieldList=name,id & filter=name contains 'smith' & sortby='id'</nowiki></tt>
:: <tt><nowiki>?fieldList=name,id&filter=name contains 'smith' & sortBy=id</nowiki></tt>
:: (See the object or view being searched for a list of field names.)
:: (See the object or view being searched for a list of field names.)


{{:REST API:Dynamic Search}}
{{:REST API:Dynamic Search}}
:'''Note:''' When searching a multi-object lookup field, the object ID (not name) must be specified.<br>Syntax: <tt>{object_id}:{record_id}</tt>
:'''Note:''' When searching a multi-object lookup field, the object ID (not name) must be specified.<br>Syntax: <tt>{object_id}:{record_id}</tt>
{{WarnSearchUppercaseFieldsForCRMObjects}}
    
    
;Response: Here is the response for a search on a custom object where ObjectName is the name of the custom object:
;Response: Here is the response for a search on a custom object where ObjectName is the name of the custom object:
Line 174: Line 94:
<platform>
<platform>
     <record>
     <record>
         <field1>...</field1>
         <field1>...value...</field1>
         <field2>...</field2>
         <field2>...value...</field2>
        <field3 displayValue="...">...value...</field3>
     </record>
     </record>
     ...
     ...
Line 181: Line 102:
         <code>0</code>
         <code>0</code>
         <description>Success</description>
         <description>Success</description>
        </message>
    </message>
     <recordCount>30</recordCount>
     <recordCount>30</recordCount>
</platform>
</platform>
</syntaxhighlight>
</syntaxhighlight>
:'''Notes:'''
:* An enumerated field returns the field label in the <tt>displayValue</tt> attribute. The field value is returned as the data inside the tag.


;Response: Here is the response for a search on a database view where ObjectName is the DatabaseViewId:
;Response: Here is the response for a search on a database view where ObjectName is the DatabaseViewId:
Line 211: Line 134:


;Method:POST
;Method:POST
;URI:<tt><nowiki>http://host/networking/rest/record/{objectName}?{query_parameters}</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/record/{objectName}?{query_parameters}</tt>


{{Query Parameters|
{{Query Parameters|
Line 242: Line 165:
</platform>
</platform>
</syntaxhighlight>
</syntaxhighlight>
==== Create record with specific ID ====
You can define your own record ID while creating a record through REST. If the record ID you provide already exists, then the record creation fails. If you do not provide the record ID, then the system will automatically generate the record ID.
;Method:POST
;URI:<tt>https://<domain>/networking/rest/record/{objectName}</tt>
;Request:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
  <record>
      <field1>…</field1>
      <field2>…</field2>…
      <PLATFORM.PARAMS.RECORD.RECORD_ID_IN_PARAMS>{recordId}</PLATFORM.PARAMS.RECORD.RECORD_ID_IN_PARAMS>
  </record>
</platform>
</syntaxhighlight>
{{Note| Record ID must be a number and cannot begin with zero.}}


===Update a Record===
===Update a Record===
Line 248: Line 187:
;Method:PUT
;Method:PUT


;URI:<tt><nowiki>https://{domain}/networking/rest/record/{objectName}/{recordId}?{query_parameters}</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/record/{objectName}/{recordId}?{query_parameters}</tt>


{{Query Parameters|
{{Query Parameters|
Line 273: Line 212:
:<syntaxhighlight lang="xml" enclose="div">
:<syntaxhighlight lang="xml" enclose="div">
<platform>
<platform>
     <message>
     <message>
         <code>0</code>
         <code>0</code>
Line 283: Line 223:
:*If <tt><nowiki>?retrieveRecord=true</nowiki></tt>, the record is also returned
:*If <tt><nowiki>?retrieveRecord=true</nowiki></tt>, the record is also returned
:*If <tt><nowiki>?retrieveRecord=false</nowiki></tt> or is not present, the record is not returned
:*If <tt><nowiki>?retrieveRecord=false</nowiki></tt> or is not present, the record is not returned
=== Update a record using filter ===
You can update a record using filter criteria.
;URI:<tt>{{platformURL}}/networking/rest/record/{objectName}?filter=someField equals 'test'</tt>
;Method:PUT
;Request:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
<record>
  <field1>…</field1>
  <field2>…</field2>…
</record>
</platform>
</syntaxhighlight>
'''Notes:'''
:1. For more examples on filtering criteria to filter records, see [[REST API:Filter Expressions in REST APIs]] and the [[REST API]] Examples.
:2. In case the filter criteria (filter=someField equals '123') matches multiple records, '''only the first record gets updated''' based on '''sortOrder''' and '''sortBy''' parameters.
::Example: filter=someField equals ‘test’&sortBy=<columnName>&sortOrder=<asc/desc>
::By default '''sortOrder''' is '''‘desc’''' & '''sortBy'''(Column to be sorted) is '''‘date_modified’'''.


===Delete a Record===
===Delete a Record===
Line 288: Line 246:


;Method:DELETE
;Method:DELETE
;URI:<tt><nowiki>https://{domain}/networking/rest/record/{objectName}/{recordId}</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/record/{objectName}/{recordId}{query_parameters}</tt>
 
{{Query Parameters|
:These query parameters are required only if a request is for deletion of attachments from the record form. All the parameters are mandatory.
:* <tt>recordFormAttachmentId</tt> (Attachment ID)
:* <tt>isRecordFormImageField</tt>  
:**<tt>true</tt>: if it is an image field
:**<tt>false</tt>: if it is a file field
:* <tt>recordFormAttachmentColumnName</tt> (Attachment field name) }}


;Request:
;Request:
Line 311: Line 277:
;Method:POST
;Method:POST


;URI:<tt><nowiki>http://host/networking/rest/record/{objectName}?{query_parameters}</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/record/{objectName}?{query_parameters}</tt>


{{Query Parameters|
{{Query Parameters|
:* <tt>isBase64Encoded</tt> (optional)
::*  <tt>true</tt>: File content is encoded binary data For example, an image.
::*  '''<tt>false</tt>''': File content is not encoded. For example, a text file. (default)
:* <tt>retrieveRecord</tt> (optional)
:* <tt>retrieveRecord</tt> (optional)
:**<tt>true</tt>: the record is also returned
::* <tt>true</tt>: the record is also returned
:**'''<tt>false</tt>''': the record is not returned (default)}}
::* '''<tt>false</tt>''': the record is not returned (default)}}


;Request:
;Request:
Line 323: Line 292:


--.............................103832778631715
--.............................103832778631715
Content-Disposition: form-data; name="xmlPart"
Content-Disposition: form-data; name="__xml_data__"
content-type: application/xml
content-type: application/xml


Line 344: Line 313:
:The Content-type of the request is set to <tt>multipart/form-data</tt> with an appropriate boundary.  
:The Content-type of the request is set to <tt>multipart/form-data</tt> with an appropriate boundary.  


:The first part contains the xml record post request and has a Content-type <tt>application/xml</tt> or <tt>application/json</tt>. The <tt><image_field></tt> field contains the file name: <tt>image1.jpg</tt>.  
:The first part contains the xml record post request and has a Content-type <tt>application/xml</tt> or <tt>application/json</tt>. The name of the part is either <tt>__xml_data__</tt> or <tt>__json_data__</tt>.
 
:The <tt><image_field></tt> field contains the file name: <tt>image1.jpg</tt>.  


:The next part of the request is the actual file. The Content-type is <tt>application/octet-stream</tt>. Note that the 'name' attribute in the content disposition points to the image field tag in the xml of the first part (ie. 'image_field'). This links the file part to the respective field in the xml. The 'filename' attribute of the content disposition is the file name of the file being uploaded to that field (i.e. <tt>image1.jpg</tt>).
:The next part of the request is the actual file. The Content-type is <tt>application/octet-stream</tt>. Note that the 'name' attribute in the content disposition points to the image field tag in the xml of the first part (ie. 'image_field'). This links the file part to the respective field in the xml. The 'filename' attribute of the content disposition is the file name of the file being uploaded to that field (i.e. <tt>image1.jpg</tt>).
Line 389: Line 360:
             //Add a record to a custom object called "HOMEPAGE"
             //Add a record to a custom object called "HOMEPAGE"
             PostMethod postMethod = new  
             PostMethod postMethod = new  
                 PostMethod("http://{domain}/networking/rest/record/HOMEPAGE/");
                 PostMethod("https://{{domain}}/networking/rest/record/HOMEPAGE/");
              
              
             //Set the session for this request.
             //Set the session for this request.
Line 402: Line 373:


             //Create the xml part of the request
             //Create the xml part of the request
             //Note the attribute '__xml_data__', the key of the string part is required.
             // __xml_data__ is required for the name attribute
             // If the content type is json use __json_data__
             // If the content type is json, use __json_data__
             StringPart sp = new StringPart("__xml_data__",
             StringPart sp = new StringPart("__xml_data__",
               "<platform><record><field1>Some text field</field1>"
               "<platform><record><field1>Some text field</field1>"
Line 432: Line 403:
;Method:PUT
;Method:PUT


;URI:<tt><nowiki>http://host/networking/rest/record/{objectName}/{recordId}?{query_parameters}</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/record/{objectName}/{recordId}?{query_parameters}</tt>


{{Query Parameters|
{{Query Parameters|
:* <tt>isBase64Encoded</tt> (optional)
::*  <tt>true</tt>: File content is encoded binary data For example, an image.
::*  '''<tt>false</tt>''': File content is not encoded. For example, a text file. (default)
:* <tt>retrieveRecord</tt> (optional)
:* <tt>retrieveRecord</tt> (optional)
:**<tt>true</tt>: the record is also returned
::* <tt>true</tt>: the record is also returned
:**'''<tt>false</tt>''': the record is not returned (default)}}
::* '''<tt>false</tt>''': the record is not returned (default)}}


;Request:
;Request:
Line 481: Line 455:
             //Update a record in a custom object called "HOMEPAGE"
             //Update a record in a custom object called "HOMEPAGE"
             PutMethod PutMethod =  
             PutMethod PutMethod =  
               new PutMethod("http://{domain}/networking/rest/record/HOMEPAGE/{recordId}");
               new PutMethod("https://{{domain}}/networking/rest/record/HOMEPAGE/{recordId}");
              
              
             //Set the session for this request.
             //Set the session for this request.
Line 494: Line 468:


             //Create the xml part of the request
             //Create the xml part of the request
             //Note the attribute '__xml_data__', the key of the string part is required.
             // __xml_data__ is required for the name attribute
             //If the content type is json use __json_data__
             // If the content type is json, use __json_data__
             StringPart sp = new StringPart("__xml_data__",
             StringPart sp = new StringPart("__xml_data__",
                 "<platform><record><field1>Some text field</field1>"
                 "<platform><record><field1>Some text field</field1>"
Line 516: Line 490:
}
}
</syntaxhighlight>
</syntaxhighlight>
 
<noinclude>
 


[[Category:REST API|record Resource]]
[[Category:REST API|record Resource]]
</noinclude>

Latest revision as of 09:00, 4 August 2017

Manage Object records using the REST API.

See also:
  • The REST bulk record resource to work with multiple records at one time.
  • The REST composite record resource to work with a record and related records in other objects.

About the Record Resource

Available Objects

These objects are available in the record Resource

Predefined Custom Object Fields

Every Custom Object is created with a number of fields that are automatically modified for each record.
Learn more: Custom Object#Predefined Fields

Data Format for Different Field Types

When adding and updating records, the field type determines the data format.
Learn more: REST API:Field Type Reference

Special Considerations for Enumerated Fields

When a record contains Enumerated Fields, there are additional factors to take into account.
Learn more: Enumerated Field Behavior For REST Web Services

Special System Objects

These System Objects can not be retrieved using the record Resource. They have specific resource URLs, instead:

Requirements

  • The logged-in user must have the permissions needed to access and/or modify the object in question.
Record access:

Lock-tiny.gif

  • In general, any user who can access an object can view all of the records it contains. (To access the object, they must be granted access to an application that contains it.)
  • One special case occurs when a record is owned by some other member of their team. In that case, the record becomes invisible, unless View permission has enabled in their Role Permissions, or unless their Access Profile gives them Global View permission.
  • Another special case occurs when Record Level Visibility has been enabled for an object, and visibility criteria has been specified for an individual record. In that case, a user who can see the record only when (a) They have been granted access to an application that contains the object, and (b) They match the visibility criteria specified for that record.
  • Users with Add permission enabled in Role Permissions or the Access Profile can add records
  • Users with Update permission enabled in Role Permissions or the Access Profile can update records
  • Users with Delete permission enabled in Role Permissions or the Access Profile can delete records 
Access to records owned by other team members:

Lock-tiny.gif

unless Record Level Visibility has been enabled, and visibility criteria has been specified for a record. (In that case, only users who match the criteria can read the record.)

Retrieve a Record

Identifies and retrieves a single record in an Object

Method
GET
URI
https://{yourDomain}/networking/rest/record/{objectName}/{recordId}
https://{yourDomain}/networking/rest/record/{objectName}/{recordId}?retrieveRecordPermissions=true
where the optional Retrieve Record Permissions Query Parameter adds extra data that tells whether the user has add or delete capabilities.
Response
<platform>
  <record>
    <field1>...value...</field1>
    <field2>...value...</field2>
    <field3 displayValue="...">...value...</field3></record>
</platform>
Notes:
  • An enumerated field returns the field label in the displayValue attribute. The field value is returned as the data inside the tag.
  • A Multi Object Lookup field has two attributes, in addition to the type attribute that is specified when you do an add or update. The syntax looks like this:
<field_name type="{objectName}" 
    uri="{REST_resource_record_id}" 
    display_value="{textual_record_identifier}">{record_id}</field>
where the Record Locator is the information that is displayed for the selected record.
  • For example, in the Sample Order Processing System, if priority tags were in a separate table, then the contents of the tag field might look like this:
<tag type="Priority_Tag" 
    uri="https://{{domain}}/networking/rest/record/Priority_Tag/9467890" 
    displayValue="Rush, Overnight">9467890</tag>

Dynamic Search

Method
GET
URI
https://{yourDomain}/networking/rest/record/{objectName}?{query_params}
https://{yourDomain}/networking/rest/record/{objectName}?{query_params}&retrieveRecordPermissions=true
where:
Sample Search
?fieldList=name,id&filter=name contains 'smith' & sortBy=id
(See the object or view being searched for a list of field names.)
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
  • 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:
<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>
  • 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
Note: When searching a multi-object lookup field, the object ID (not name) must be specified.
Syntax: {object_id}:{record_id}
Response
Here is the response for a search on a custom object where ObjectName is the name of the custom object:
<platform>
    <record>
        <field1>...value...</field1>
        <field2>...value...</field2>
        <field3 displayValue="...">...value...</field3>
    </record>
    ...
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
    <recordCount>30</recordCount>
</platform>
Notes:
  • An enumerated field returns the field label in the displayValue attribute. The field value is returned as the data inside the tag.
Response
Here is the response for a search on a database view where ObjectName is the DatabaseViewId:
<platform>
    <record>
        <alias1.fileName1>value1</alias1.fileName1>
        <alias1.fileName2>value1</alias1.fileName2>
        <alias2.fileName1>value1</alias2.fileName1>
        <alias2.fileName2>value1</alias2.fileName2>
        ...
    </record>
    <record>
    ...
    </record>
        <message>
            <code>0</code>
            <description>Success</description>
        </message>
    <recordCount>30</recordCount>
</platform>

Add a Record

Adds a record to an Object

Method
POST
URI
https://{yourDomain}/networking/rest/record/{objectName}?{query_parameters}
Query Parameters
  • retrieveRecord (optional)
    • true: the record is also returned
    • false: the record is not returned (default)
For more information, see: Specifying Query Parameters in REST APIs
Request
<platform>
    <record>
        <field1>...</field1>
        <field2>...</field2>
        ...
        ...
    </record>
</platform>
Notes:
  • Each <fieldN> element has the name of a field in the object. For example:
<company_name>ABC Co.</company_name>
<street_address>21 Jump Street</street_address>
  • When specifying a Multi Object Lookup field, you specify the object identifier (name or ID) in the type attribute, and the record ID as the field value. The syntax looks like this:
<field_name type="{objectName}">{record_id}</field>
For example, in the Sample Order Processing System, if priority tags were in a separate table, then the field might look like this:
<tag type="Priority_Tag">9467890</tag>
  • To not trigger the rules via REST API, use the following parameter:
<PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY>1</PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY>
Response
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
    <id>...</id>     <!-- record ID -->  
</platform>

Create record with specific ID

You can define your own record ID while creating a record through REST. If the record ID you provide already exists, then the record creation fails. If you do not provide the record ID, then the system will automatically generate the record ID.

Method
POST
URI
https://<domain>/networking/rest/record/{objectName}
Request
<platform>
   <record>
      <field1></field1>
      <field2></field2><PLATFORM.PARAMS.RECORD.RECORD_ID_IN_PARAMS>{recordId}</PLATFORM.PARAMS.RECORD.RECORD_ID_IN_PARAMS>
   </record>
</platform>

Notepad.png

Note: Record ID must be a number and cannot begin with zero.

Update a Record

Updates a record in an Object.

Method
PUT
URI
https://{yourDomain}/networking/rest/record/{objectName}/{recordId}?{query_parameters}
Query Parameters
  • retrieveRecord (optional)
    • true: the record is also returned
    • false: the record is not returned (default)
For more information, see: Specifying Query Parameters in REST APIs
Request
<platform>
    <record>
        <field1>...</field1>
        <field2>...</field2>
        ...
        ...
    </record>
</platform>
Notes:
  • Each <fieldN> element has the name of a field in the object. For example:
<company_name>ABC Co.</company_name>
<street_address>21 Jump Street</street_address>
  • When specifying a Multi Object Lookup field, you specify the object identifier (name or ID) in the type attribute, and the record ID as the field value. The syntax looks like this:
<field_name type="{objectName}">{record_id}</field>
For example, in the Sample Order Processing System, if priority tags were in a separate table, then the field might look like this:
<tag type="Priority_Tag">9467890</tag>
  • To not trigger the rules via REST API, use the following parameter:
<PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY>1</PLATFORM.PARAMS.RECORD.DO_NOT_EXEC_DATA_POLICY>
Response
<platform>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

If the ?retrieveRecord=true query is included:

  • If ?retrieveRecord=true, the record is also returned
  • If ?retrieveRecord=false or is not present, the record is not returned

Update a record using filter

You can update a record using filter criteria.

URI
https://{yourDomain}/networking/networking/rest/record/{objectName}?filter=someField equals 'test'
Method
PUT
Request
<platform>
<record>
  <field1></field1>
  <field2></field2></record>
</platform>

Notes:

1. For more examples on filtering criteria to filter records, see REST API:Filter Expressions in REST APIs and the REST API Examples.
2. In case the filter criteria (filter=someField equals '123') matches multiple records, only the first record gets updated based on sortOrder and sortBy parameters.
Example: filter=someField equals ‘test’&sortBy=<columnName>&sortOrder=<asc/desc>
By default sortOrder is ‘desc’ & sortBy(Column to be sorted) is ‘date_modified’.

Delete a Record

Deletes a record in an Object

Method
DELETE
URI
https://{yourDomain}/networking/rest/record/{objectName}/{recordId}{query_parameters}
Query Parameters
These query parameters are required only if a request is for deletion of attachments from the record form. All the parameters are mandatory.
  • recordFormAttachmentId (Attachment ID)
  • isRecordFormImageField
    • true: if it is an image field
    • false: if it is a file field
  • recordFormAttachmentColumnName (Attachment field name)
For more information, see: Specifying Query Parameters in REST APIs
Request

No request body accompanies the resource.

Response
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

Multipart Operations for Raw Data

To include binary data in an XML stream, it is encoded and included in a multipart REST request (a request that contains a normal XML segment and an additional segment for each request field that holds raw data).

Add a Multipart Record

Adds a record to an Object when one or more fields contain raw data.

Method
POST
URI
https://{yourDomain}/networking/rest/record/{objectName}?{query_parameters}
Query Parameters
  • isBase64Encoded (optional)
  • true: File content is encoded binary data For example, an image.
  • false: File content is not encoded. For example, a text file. (default)
  • retrieveRecord (optional)
  • true: the record is also returned
  • false: the record is not returned (default)
For more information, see: Specifying Query Parameters in REST APIs
Request
Content-Type: multipart/form-data; boundary=.............................103832778631715

--.............................103832778631715
Content-Disposition: form-data; name="__xml_data__"
content-type: application/xml

    <platform>
        <record>
            <field1>...</field1>
            <field2>...</field2>
            <image_field>image1.jpg</image_field>
             ...
        </record>
    </platform>
.............................103832778631715
Content-Disposition: form-data; name="image_field"; filename="image1.jpg"
content-type: application/octet-stream

{encoded contents of file}
.............................103832778631715--
The Content-type of the request is set to multipart/form-data with an appropriate boundary.
The first part contains the xml record post request and has a Content-type application/xml or application/json. The name of the part is either __xml_data__ or __json_data__.
The <image_field> field contains the file name: image1.jpg.
The next part of the request is the actual file. The Content-type is application/octet-stream. Note that the 'name' attribute in the content disposition points to the image field tag in the xml of the first part (ie. 'image_field'). This links the file part to the respective field in the xml. The 'filename' attribute of the content disposition is the file name of the file being uploaded to that field (i.e. image1.jpg).
Multiple files can be attached to their respective fields in that manner.
Response
 <platform>
     <message>
         <code>0</code>
         <description>Success</description>
     </message>
 </platform>
See also: REST API:Error Codes
Sample Client
Here is a sample client that uploads an image to an image field.
import java.io.File;

import javax.ws.rs.core.MediaType;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.URI;
import org.apache.commons.httpclient.methods.PutMethod;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;

public class MultipartRecord
{
    public static void main(String[] args)
    {
        try
        {
            File f = new File("c:\\csvs\\image1.jpg");
            
            HttpClient client = new HttpClient();

            //Add a record to a custom object called "HOMEPAGE"
            PostMethod postMethod = new 
                PostMethod("https://{{domain}}/networking/rest/record/HOMEPAGE/");
            
            //Set the session for this request.
            postMethod.setRequestHeader("Cookie", "JSESSIONID=A741270662A86F796DA16646F0708C43");

            //The first attribute of the FilePart constructor refers to the image field name 
            //ie.image_field
            FilePart filePart = new FilePart("image_field", f);
            
            //Set the content type of the filePart
            filePart.setContentType(MediaType.APPLICATION_OCTET_STREAM);

            //Create the xml part of the request
            // __xml_data__ is required for the name attribute 
            // If the content type is json, use __json_data__
            StringPart sp = new StringPart("__xml_data__",
              "<platform><record><field1>Some text field</field1>"
            + "<image_field>image1.jpg</image_field></record></platform>");
            
            //Set the Content-type of the xml part
            sp.setContentType(MediaType.APPLICATION_XML);
            
            final Part[] parts = { sp, filePart };

            postMethod.setRequestEntity(new MultipartRequestEntity(parts, postMethod.getParams()));

            int executeMethod = client.executeMethod(postMethod);
        }
        catch(Exception e)
        {
            System.out.println("Exception");
        }
    }
}

Update a Multipart Record

Updates a record in an Object when one or more fields contain raw data.

Notepad.png

Note: Normal update rules are observed. For example, if an image field is specified, and the existing record field already contains an image, then the old image is deleted and the new one is uploaded in it's place.

Method
PUT
URI
https://{yourDomain}/networking/rest/record/{objectName}/{recordId}?{query_parameters}
Query Parameters
  • isBase64Encoded (optional)
  • true: File content is encoded binary data For example, an image.
  • false: File content is not encoded. For example, a text file. (default)
  • retrieveRecord (optional)
  • true: the record is also returned
  • false: the record is not returned (default)
For more information, see: Specifying Query Parameters in REST APIs
Request
The format of the request is identical to that shown in Add a Multipart Record.
Response
      <platform>
          <message>
              <code>0</code>
              <description>Success</description>
          </message>
      </platform>
See also: REST API:Error Codes
Sample Client
Here is a sample client that updates an image in an image field.
import java.io.File;

import javax.ws.rs.core.MediaType;

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.URI;
import org.apache.commons.httpclient.methods.PutMethod;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.commons.httpclient.methods.multipart.StringPart;


public class MultipartRecord
{
    public static void main(String[] args)
    {
        try
        {
            File f = new File("c:\\csvs\\image1.jpg");
            
            HttpClient client = new HttpClient();

            //Update a record in a custom object called "HOMEPAGE"
            PutMethod PutMethod = 
               new PutMethod("https://{{domain}}/networking/rest/record/HOMEPAGE/{recordId}");
            
            //Set the session for this request.
            PutMethod.setRequestHeader("Cookie", "JSESSIONID=A741270662A86F796DA16646F0708C43");

            //The first attribute of the FilePart constructor refers to 
            //the image field name ie.image_field
            FilePart filePart = new FilePart("image_field", f);
            
            //Set the content type of the filePart
            filePart.setContentType(MediaType.APPLICATION_OCTET_STREAM);

            //Create the xml part of the request
            // __xml_data__ is required for the name attribute 
            // If the content type is json, use __json_data__
            StringPart sp = new StringPart("__xml_data__",
                "<platform><record><field1>Some text field</field1>"
              + "<image_field>image1.jpg</image_field></record></platform>");
            
            //Set the Content-type of the xml part
            sp.setContentType(MediaType.APPLICATION_XML);
            
            final Part[] parts = { sp, filePart };

            PutMethod.setRequestEntity(new MultipartRequestEntity(parts, PutMethod.getParams()));

            int executeMethod = client.executeMethod(PutMethod);
        }
        catch(Exception e)
        {
            System.out.println("Exception");
        }
    }
}