AgileApps Support Wiki

Difference between revisions of "REST API:document Resource"

From AgileApps Support Wiki
imported>Aeric
(Created page with "{{subst:REST Resource}}")
 
imported>Aeric
(Replaced content with "Access stored [{Documents]] using the REST API. :''Learn more:'' REST API Conventions and Considerations. ===Get a Document=…")
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]]
Download 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><nowiki>https://{domain}/networking/rest/document/{documentId}</nowiki></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">
Download is intitiated.
<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|__resourceName__ Resource]]
</noinclude>
</noinclude>
-->

Revision as of 22:47, 12 August 2011

Access stored [{Documents]] using the REST API.

Learn more: REST API Conventions and Considerations.

Get a Document

Download a stored document.

Method
GET
URI
https://{domain}/networking/rest/document/{documentId}
Response

Download is intitiated.

Retrieved from "https://agileappscloud.info/aawiki-src/index.php?title=REST_API:document_Resource&oldid=14497"