Difference between revisions of "REST API:document Resource"

From AgileApps Support Wiki
imported>Aeric
(Created page with "{{subst:REST Resource}}")
Β 
imported>Aeric
Β 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
Manage __resourceName__ (record)s using the [[REST API]].
Access stored documents 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:
===Get a Document===
# Add an entry to the [[REST API:REST API CheatSheet|REST API CheatSheet]]
Access a stored document.
# 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===
{{TBD|Are the permission(s) right?}} -- check [[Administrative Permissions]] for a list of possibilities
:* [[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.)


;Method:GET
;Method:GET
Β  Β 
Β  Β 
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__</nowiki></tt>
;URI:<tt>{{platformURL}}/rest/document/{documentId}</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">
:* Document content, as multi-part data.
<platform>
Β  Β  <__resourceName__>
Β  Β  Β  Β  <id>...</id>
Β  Β  Β  Β  <field>data</field>
Β  Β  Β  Β  ...
Β  Β  </__resourceName__>
Β 
Β  Β  <__resourceName__>
Β  Β  Β  Β  ...
Β  Β  </__resourceName__>
Β 
Β  Β  ...
Β 
Β  Β  <message>
Β  Β  Β  Β  <code>0</code>
Β  Β  Β  Β  <description>Success</description>
Β  Β  </message>
Β  Β  <recordCount>N</recordCount>Β  Β  Β  <!-- Number of __ records returned -->
</platform>
</syntaxhighlight>
Β 
:See also: [[REST API:Error Codes]]
Β 
===Get a __resourceName__ Record===
;Method:GET
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__/{recordId}</nowiki></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:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
Β  Β  <__resourceName__>
Β  Β  Β  Β  <id>...</id>
Β  Β  Β  Β  <field>data</field>
Β  Β  Β  Β  ...
Β  Β  </__resourceName__>
Β 
Β  Β  <message>
Β  Β  Β  Β  <code>0</code>
Β  Β  Β  Β  <description>Success</description>
Β  Β  </message>
</platform>
</syntaxhighlight>
Β 
:See also: [[REST API:Error Codes]]
Β 
===Add a __resourceName__ Record===
Β 
;Method:POST
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__</nowiki></tt>
Β 
;Request:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
Β  Β  <__resourceName__>
Β  Β  Β  Β  <field>data</field>
Β  Β  Β  Β  ...
Β  Β  </__resourceName__>
</platform>
</syntaxhighlight>
Β 
;Response:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
Β  Β  <message>
Β  Β  Β  Β  <code>0</code>
Β  Β  Β  Β  <description>Success</description>
Β  Β  Β  Β  <id>...</id>Β  <!-- ID of the newly created __resourceName__ -->
Β  Β  </message>
</platform>
</syntaxhighlight>
Β 
:See also: [[REST API:Error Codes]]
Β 
===Update a __resourceName__ Record===
;Method:PUT
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__/{recordId}</nowiki></tt>
Β 
;Request:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
Β  Β  <__resourceName__>
Β  Β  Β  Β  <id>{recordId}</id>
Β  Β  Β  Β  ...
Β  Β  </__resourceName__>
</platform>
</syntaxhighlight>
Β 
;Response:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
Β  Β  <message>
Β  Β  Β  Β  <code>0</code>
Β  Β  Β  Β  <description>Success</description>
Β  Β  </message>
</platform>
</syntaxhighlight>
Β 
:See also: [[REST API:Error Codes]]
Β 
===Delete a __resourceName__ Record ===
Β 
;Method:DELETE
Β 
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__/{recordId}</nowiki></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:
:<syntaxhighlight lang="xml" enclose="div">
<platform>
Β  Β  ....
Β  Β  <message>
Β  Β  Β  Β  <code>0</code>
Β  Β  Β  Β  <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".
:{| border="1" cellpadding="5" cellspacing="0"
! Name!!Type!!Attribute!!Required on Add!!Description!!Additional Information
|-
| id || String || align="center"|Read Only || || || [[Record Id]]
|-
| name || String || || align="center"|[[File:Checkmark.gif|link=]] || ||
|-
| description || String || || || ||
|-
| ...|| ... || ... || ... || ... || ...
|-
| tag || String || align="center"|Read Only || || description || AddlInfo
|-
| tag || String || || || description || AddlInfo
|-
| 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
|-
| ...|| ... || ... || ... || ... || ...
|-
| ...|| ... || ... || ... || ... || ...
|-
| date_modified || Date || align="center"|Read Only || || || [[UTC Format]]
|-
| 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
|}
-or-
:{| border="1" cellpadding="5" cellspacing="0"
! Name !! Type !! Attribute !! Default Value !! Description !! Additional Information
|-
| tag || String || align="center"|Read Only || Default || description || AddlInfo
|-
| tag || String ||Β  || Default || description || AddlInfo
|-
| ...|| ... || ... || ... || ... || ...
|-
| ...|| ... || ... || ... || ... || ...
|-
| date_modified || Date || align="center"|Read Only || || || [[UTC Format]]
|-
| 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==
Β 
===Add a ...===
(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|document Resource]]
</noinclude>
</noinclude>
-->

Latest revision as of 20:56, 25 June 2013

Access stored documents using the REST API.

Learn more: REST API Conventions and Considerations.

Get a Document

Access a stored document.

Method
GET
URI
https://{yourDomain}/networking/rest/document/{documentId}
Response
  • Document content, as multi-part data.