AgileApps Support Wiki Pre Release

Difference between revisions of "REST API:index Resource"

From AgileApps Support Wiki
imported>Aeric
(Created page with "{{subst: REST Resource}}")
 
imported>Aeric
 
(26 intermediate revisions by the same user not shown)
Line 1: Line 1:
Manage __resourceName__ (record)s using the [[REST API]].
Manage index metadata for an Object using the [[REST API]].


:''Learn more:'' REST API [[REST API#Conventions and Considerations|Conventions and Considerations]].
:''Learn more:'' REST API [[REST API#Conventions and Considerations|Conventions and Considerations]].
{{Note|Use this structure the same way you use the structure for man pages:<br/>Follow the presentation pattern, but if a section isn't needed, don't include the header.<br/>Also:
# Add an entry to the [[REST API:REST API CheatSheet|REST API CheatSheet]]
# Add an entry to the [[REST API]] (categorized) page
# Add an entry to the [[REST API:REST Resources (alphabetical)|REST Resources]] page
}}
===Requirements===
:* Requirement #1
:* Requirement #2


===Permissions===
===Permissions===
{{TBD|Are the permission(s) right?}} -- check [[Administrative Permissions]] for a list of possibilities
{{permissions|Use Development Features|use this resource.}}
:* [[Develop Tools]] permission must be enabled for the tenant.
{{permissions|Access Control/User Management|use this resource.}}
{{permissions|Manage Develop Features|use this resource.}}
 
===List All __resourceName__ (Record)s===
("Get" if complete records are returned. "List" if partial data is returned, requiring a second read to get a complete set of data. This comes before the GET, because typically it's called first to get the ID used in a specific-record GET.)


===Get a List of Object Indexes===
;Method:GET
;Method:GET
   
   
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/index/{objectName}</tt>  
:Return all fields
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__?{query_parameters}</nowiki></tt>  
 
{{Query Parameters|
:Introductory sentence, if any
:*<tt>parameter1</tt> - Description
:*<tt>parameter2</tt>
::* If TRUE, ...
::* If FALSE, ...}}


;Response:
;Response:
:<syntaxhighlight lang="xml" enclose="div">
:<syntaxhighlight lang="xml" enclose="div">
<platform>
<platform>
     <__resourceName__>
     <index>
         <id>...</id>
         <name>AuthorIndex</name>
         <field>data</field>
         <uniqueIndex>false</uniqueIndex>
        ...
        <useInImportForMerge>false</useInImportForMerge>
     </__resourceName__>
        <indexFields>author_name</indexFields>
     </index>


     <__resourceName__>
     <index>
         ...
         ...
     </__resourceName__>
     </index>


     ...
     ...
Line 54: Line 31:
         <description>Success</description>
         <description>Success</description>
     </message>
     </message>
     <recordCount>N</recordCount>      <!-- Number of __ records returned -->
     <recordCount>N</recordCount>      <!-- Number of indexes returned -->
</platform>
</platform>
</syntaxhighlight>
</syntaxhighlight>
Line 60: Line 37:
:See also: [[REST API:Error Codes]]
:See also: [[REST API:Error Codes]]


===Get a __resourceName__ Record===
===Get an Object Index ===
;Method:GET
;Method:GET
   
   
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__/{recordId}</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/index/{objectName}/{indexName}</tt>
:Return all fields
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__/{recordId}?{query_parameters}</nowiki></tt>
{{Query Parameters|
:Introductory sentence, if any
::*<tt>parameter1</tt> - Description
::*<tt>parameter2</tt>
:::* If <tt>true</tt>, ...
:::* If '''<tt>false</tt>''', ... ('''default''')}}


;Response:
;Response:
:<syntaxhighlight lang="xml" enclose="div">
:<syntaxhighlight lang="xml" enclose="div">
<platform>
<platform>
     <__resourceName__>
     <index>
         <id>...</id>
         <id>a5baa89caa064ed995c6c14f402db379</id>
         <field>data</field>
        <objectName>Books</objectName>
        ...
        <name>AuthorIndex</name>
     </__resourceName__>
        <uniqueIndex>false</uniqueIndex>
        <useInImportForMerge>false</useInImportForMerge>
        <indexFields>author_name</indexFields>
        <date_created>2012-02-09T08:00:00.000Z</date_created>
         <date_modified>2012-02-13T08:00:00.000Z</date_modified>
        <modified_id
            type="USER" uri="..."
            displayValue="...">...userId...</modified_id>
     </index>


     <message>
     <message>
Line 91: Line 68:
:See also: [[REST API:Error Codes]]
:See also: [[REST API:Error Codes]]


===Add a __resourceName__ Record===
===Add an Index to an Object===


;Method:POST
;Method:POST
   
   
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__</nowiki></tt>  
;URI:<tt>{{platformURL}}/rest/index/{objectName}</tt>  


;Request:
;Request:
:<syntaxhighlight lang="xml" enclose="div">
:<syntaxhighlight lang="xml" enclose="div">
<platform>
<platform>
     <__resourceName__>
     <index>
         <field>data</field>
         <name>IBSN_Index</name>
        ...
        <uniqueIndex>false</uniqueIndex>
     </__resourceName__>
        <useInImportForMerge>false</useInImportForMerge>
        <indexFields>ibsn_number</indexFields>
     </index>
</platform>
</platform>
</syntaxhighlight>
</syntaxhighlight>
Line 113: Line 92:
         <code>0</code>
         <code>0</code>
         <description>Success</description>
         <description>Success</description>
         <id>...</id>  <!-- ID of the newly created __resourceName__ -->
         <id>...</id>  <!-- ID of the newly created index -->
     </message>
     </message>
</platform>
</platform>
Line 120: Line 99:
:See also: [[REST API:Error Codes]]
:See also: [[REST API:Error Codes]]


===Update a __resourceName__ Record===
===Update an Object Index ===
;Method:PUT
;Method:PUT
   
   
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__/{recordId}</nowiki></tt>  
;URI:<tt>{{platformURL}}/rest/index/{objectName}/{indexName}</tt>  


;Request:
;Request:
:(Only one field can be updated.)
:<syntaxhighlight lang="xml" enclose="div">
:<syntaxhighlight lang="xml" enclose="div">
<platform>
<platform>
     <__resourceName__>
     <index>
        <id>{recordId}</id>
      <useInImportForMerge>true</useInImportForMerge>
        ...
     </index>
     </__resourceName__>
</platform>
</platform>
</syntaxhighlight>
</syntaxhighlight>
Line 147: Line 126:
:See also: [[REST API:Error Codes]]
:See also: [[REST API:Error Codes]]


===Delete a __resourceName__ Record ===
===Delete an Object Index ===


;Method:DELETE
;Method:DELETE


;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__/{recordId}</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/index/{objectName}/{indexName}</tt>
 
;Response:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
</syntaxhighlight>
 
:See also: [[REST API:Error Codes]]
 
===Dynamic Search for __resourceName__ Records===
;Method:GET
 
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__?{query_parameters}</nowiki></tt>
{{:REST API:Dynamic Search}}


;Response:
;Response:
:<syntaxhighlight lang="xml" enclose="div">
:<syntaxhighlight lang="xml" enclose="div">
<platform>
<platform>
    ....
     <message>
     <message>
         <code>0</code>
         <code>0</code>
Line 186: Line 146:
===Fields===
===Fields===
:''Note:'' Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".
:''Note:'' Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".
:{| border="1" cellpadding="5" cellspacing="0"
:{| border="1" cellpadding="3" cellspacing="0"
! Name!!Type!!Attribute!!Required on Add!!Description!!Additional Information
! Name!!Type!!Attribute!!Required on Add!!Description!!Additional Information
|-
|-
| id || String || align="center"|Read Only || || || [[Record Id]]
| id || String || align="center"|Read&nbsp;Only || || Index ID || [[Record Id]]
|-
|-
| name || String || || align="center"|[[File:Checkmark.gif|link=]] || ||  
| objectName || String || align="center"|Read Only || || Object name ||  
|-
|-
| description || String || || || ||  
| name || String || Add Only || align="center"|[[File:Checkmark.gif|link=]] || Index name ||  
|-
|-
| ...|| ... || ... || ... || ... || ...
| indexFields || String || Add Only || align="center"|[[File:Checkmark.gif|link=]] || Fields that make up the index || Comma-separated list of field names
|-
|-
| tag || String || align="center"|Read Only || || description || AddlInfo
| uniqueIndex || Boolean || Add Only || || If true, index keys must be unique || true or '''false''' (default)
|-
|-
| tag || String || || || description || AddlInfo
| useInImportForMerge || Boolean || || || If true, index is used during an import merge || true or '''false''' (default)
|-
| tag || String || || align="center"|[[File:Checkmark.gif|link=]] || description || AddlInfo
|-
| tag || String || align="center"|Writable on Add only || align="center"|[[File:Checkmark.gif|link=]] || description || AddlInfo
|-
| ...|| ... || ... || ... || ... || ...
|-
| ...|| ... || ... || ... || ... || ...


|-  
|-  
| colspan="6"  bgcolor="Azure" style="height:7px" |  <!-- SPACER ROW -->
| colspan="6"  bgcolor="lightblue" style="height:7px" |  <!-- SPACER ROW -->


|-
|-
Line 221: Line 173:
| modified_id || Lookup || align="center"|Read Only || || || [[REST API:User Resource|User]] ID
| modified_id || Lookup || align="center"|Read Only || || || [[REST API:User Resource|User]] ID
|}
|}
-or-
 
===Error Codes===
:{| border="1" cellpadding="5" cellspacing="0"
:{| border="1" cellpadding="5" cellspacing="0"
! Name !! Type !! Attribute !! Default Value !! Description !! Additional Information
! Platform Code||with Http Status||Description
|-
| tag || String || align="center"|Read Only || Default || description || AddlInfo
|-
| tag || String ||  || Default || description || AddlInfo
|-
| ...|| ... || ... || ... || ... || ...
|-
| ...|| ... || ... || ... || ... || ...
 
|-
| colspan="6"  bgcolor="Azure" style="height:7px" |  <!-- SPACER ROW -->
 
|-
|-
| date_modified || Date || align="center"|Read Only || || || [[UTC Format]]
| align="center"| -7000 || BAD_REQUEST (400) || Invalid index name
|-
| date_created || Date || align="center"|Read Only || || || [[UTC Format]]
|-
| created_id || Lookup || align="center"|Read Only  || || || [[REST API:User Resource|User]] ID
|-
| modified_id || Lookup || align="center"|Read Only || || || [[REST API:User Resource|User]] ID
|}
|}


==Multipart Requests for Raw Data==
''Learn more:''
 
:* See the [[REST API:Error Codes]] for common Http error codes
===Add a ...===
:* See the [{{DOCHOST}}/javadocs/constant-values.html javadoc constants] for a complete list of <tt>PlatformException</tt> error-code constants.
(Add is always appropriate, because an existing file is being imported.)
 
;Method:POST
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__?{query_parameters}</nowiki></tt>
{{Query Parameters|
:Introductory sentence, if any
::*<tt>parameter1</tt> - Description
::*<tt>parameter2</tt>
:::* If <tt>true</tt>, ...
:::* If '''<tt>false</tt>''', ... ('''default''')}}
 
;Request:
:A multipart request with file part for the ... and an XML/JSON part with processing information.
 
: Here's a sample request that ...:
 
:<syntaxhighlight lang="xml" enclose="div">
Content-Type: multipart/form-data; boundary=.............................103832778631715
 
--.............................103832778631715
Content-Disposition: form-data; name="xml_part";
Content-Type=application/xml;
 
<platform>
    <record>
        ...XML DATA GOES HERE...
    </record>
</platform>
 
.............................103832778631715
Content-Disposition: form-data; name="file_part"; filename="somefile.ext"
Content-type: application/octet-stream
 
{contents of file}
.............................103832778631715--
</syntaxhighlight>
 
:''Learn more:'' [[REST API:Multipart Request]]
 
;Response:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>...</id>  // ID of the added resource
    </message>
</platform>
</syntaxhighlight>
 
:See also: [[REST API:Error Codes]]
 
===Update a ...===
;Method:PUT
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__/{recordId}?{query_parameters}</nowiki></tt>
{{Query Parameters|
:Introductory sentence, if any
::*<tt>parameter1</tt> - Description
::*<tt>parameter2</tt>
:::* If <tt>true</tt>, ...
:::* If '''<tt>false</tt>''', ... ('''default''')}}</nowiki></tt>
 
;Request:
:The format of the request is identical to that shown in [[#Add a __resourceName__|Add a __resourceName__]].
 
;Response:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>...</id>  // ID of the updated resource
    </message>
</platform>
</syntaxhighlight>
 
:See also: [[REST API:Error Codes]]
 
===Sample ... Client to ...===
ex: Sample Login Client, Sample HTTP Client to ...
 
:The [{{DOCHOST}}/samples/demo/rest/__NAME__Client.java __NAME__Client] demo program extends the [{{DOCHOST}}/samples/demo/rest/BaseClient.java BaseClient] class to __DO SOMETHING__.
 
:<syntaxhighlight lang="java" enclose="div">
...program here...
</syntaxhighlight>
<!--ACTIVATE THE CATEGORY BELOW
<noinclude>
<noinclude>


[[Category:REST API|__resourceName__ Resource]]
[[Category:REST API|index Resource]]
</noinclude>
</noinclude>
-->

Latest revision as of 00:38, 8 June 2012

Manage index metadata for an Object using the REST API.

Learn more: REST API Conventions and Considerations.

Permissions

Lock-tiny.gif

Users that have the Use Development Features permission can use this resource. 

Get a List of Object Indexes

Method
GET
URI
https://{yourDomain}/networking/rest/index/{objectName}
Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <index>
       <name>AuthorIndex</name>
       <uniqueIndex>false</uniqueIndex>
       <useInImportForMerge>false</useInImportForMerge>
       <indexFields>author_name</indexFields>
   </index>

   <index>
        ...
   </index>

    ...

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

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Get an Object Index

Method
GET
URI
https://{yourDomain}/networking/rest/index/{objectName}/{indexName}
Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <index>
       <id>a5baa89caa064ed995c6c14f402db379</id>
       <objectName>Books</objectName>
       <name>AuthorIndex</name>
       <uniqueIndex>false</uniqueIndex>
       <useInImportForMerge>false</useInImportForMerge>
       <indexFields>author_name</indexFields>
       <date_created>2012-02-09T08:00:00.000Z</date_created>
       <date_modified>2012-02-13T08:00:00.000Z</date_modified>
       <modified_id 
            type="USER" uri="..." 
            displayValue="...">...userId...</modified_id>
   </index>

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

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Add an Index to an Object

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

<platform> 

   <index>
       <name>IBSN_Index</name>
       <uniqueIndex>false</uniqueIndex>
       <useInImportForMerge>false</useInImportForMerge>
       <indexFields>ibsn_number</indexFields>
   </index>

</platform> </syntaxhighlight>

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

<platform> 

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

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Update an Object Index

Method
PUT
URI
https://{yourDomain}/networking/rest/index/{objectName}/{indexName}
Request
(Only one field can be updated.)
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <index>
     <useInImportForMerge>true</useInImportForMerge>
   </index>

</platform> </syntaxhighlight>

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

<platform> 

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

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Delete an Object Index

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

<platform> 

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

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Fields

Note: Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".
Name Type Attribute Required on Add Description Additional Information
id String Read Only Index ID Record Id
objectName String Read Only Object name
name String Add Only Checkmark.gif Index name
indexFields String Add Only Checkmark.gif Fields that make up the index Comma-separated list of field names
uniqueIndex Boolean Add Only If true, index keys must be unique true or false (default)
useInImportForMerge Boolean If true, index is used during an import merge true or false (default)
date_modified Date Read Only UTC Format
date_created Date Read Only UTC Format
created_id Lookup Read Only User ID
modified_id Lookup Read Only User ID

Error Codes

Platform Code with Http Status Description
-7000 BAD_REQUEST (400) Invalid index name

Learn more:

Retrieved from "https://agileappscloud.info/aadev-src/index.php?title=REST_API:index_Resource&oldid=16770"