AgileApps Support Wiki

REST API:document Resource

From AgileApps Support Wiki
Revision as of 22:39, 12 August 2011 by imported>Aeric (Created page with "{{subst:REST Resource}}")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Manage __resourceName__ (record)s using the REST API.

Learn more: REST API Conventions and Considerations.

Notepad.png

Note: Use this structure the same way you use the structure for man pages:
Follow the presentation pattern, but if a section isn't needed, don't include the header.
Also:

  1. Add an entry to the REST API CheatSheet
  2. Add an entry to the REST API (categorized) page
  3. Add an entry to the REST Resources page

Requirements

  • Requirement #1
  • Requirement #2

Permissions

__TBD: Are the permission(s) right?__ -- check Administrative Permissions for a list of possibilities

Lock-tiny.gif

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

Lock-tiny.gif

Users that have the Manage Develop Features permission can 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
URI
https://{domain}/networking/rest/__resourceName__
Return all fields
URI
https://{domain}/networking/rest/__resourceName__?{query_parameters}
Query Parameters
Introductory sentence, if any
  • parameter1 - Description
  • parameter2
  • If TRUE, ...
  • If FALSE, ...
For more information, see: Specifying Query Parameters in REST APIs
Response
<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>
See also: REST API:Error Codes

Get a __resourceName__ Record

Method
GET
URI
https://{domain}/networking/rest/__resourceName__/{recordId}
Return all fields
URI
https://{domain}/networking/rest/__resourceName__/{recordId}?{query_parameters}
Query Parameters
Introductory sentence, if any
  • parameter1 - Description
  • parameter2
  • If true, ...
  • If false, ... (default)
For more information, see: Specifying Query Parameters in REST APIs
Response
<platform>
    <__resourceName__>
        <id>...</id>
        <field>data</field>
         ...
    </__resourceName__>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
See also: REST API:Error Codes

Add a __resourceName__ Record

Method
POST
URI
https://{domain}/networking/rest/__resourceName__
Request
<platform>
    <__resourceName__>
        <field>data</field>
         ...
    </__resourceName__>
</platform>
Response
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>...</id>   <!-- ID of the newly created __resourceName__ -->
    </message>
</platform>
See also: REST API:Error Codes

Update a __resourceName__ Record

Method
PUT
URI
https://{domain}/networking/rest/__resourceName__/{recordId}
Request
<platform>
    <__resourceName__>
        <id>{recordId}</id>
         ...
    </__resourceName__>
</platform>
Response
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
See also: REST API:Error Codes

Delete a __resourceName__ Record

Method
DELETE
URI
https://{domain}/networking/rest/__resourceName__/{recordId}
Response
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
See also: REST API:Error Codes

Dynamic Search for __resourceName__ Records

Method
GET
URI
https://{domain}/networking/rest/__resourceName__?{query_parameters}
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
Response
<platform>
    ....
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
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 Record Id
name String Checkmark.gif
description String
... ... ... ... ... ...
tag String Read Only description AddlInfo
tag String description AddlInfo
tag String Checkmark.gif description AddlInfo
tag String Writable on Add only Checkmark.gif description AddlInfo
... ... ... ... ... ...
... ... ... ... ... ...
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

-or-

Name Type Attribute Default Value Description Additional Information
tag String Read Only Default description AddlInfo
tag String Default description AddlInfo
... ... ... ... ... ...
... ... ... ... ... ...
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

Multipart Requests for Raw Data

Add a ...

(Add is always appropriate, because an existing file is being imported.)

Method
POST
URI
https://{domain}/networking/rest/__resourceName__?{query_parameters}
Query Parameters
Introductory sentence, if any
  • parameter1 - Description
  • parameter2
  • If true, ...
  • If false, ... (default)
For more information, see: Specifying Query Parameters in REST APIs
Request
A multipart request with file part for the ... and an XML/JSON part with processing information.
Here's a sample request that ...:
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--
Learn more: REST API:Multipart Request
Response
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>...</id>   // ID of the added resource
    </message>
</platform>
See also: REST API:Error Codes

Update a ...

Method
PUT
URI
https://{domain}/networking/rest/__resourceName__/{recordId}?{query_parameters}
Query Parameters
Introductory sentence, if any
  • parameter1 - Description
  • parameter2
  • If true, ...
  • If false, ... (default)
For more information, see: Specifying Query Parameters in REST APIs</nowiki>
Request
The format of the request is identical to that shown in Add a __resourceName__.
Response
<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>...</id>   // ID of the updated resource
    </message>
</platform>
See also: REST API:Error Codes

Sample ... Client to ...

ex: Sample Login Client, Sample HTTP Client to ...

The __NAME__Client demo program extends the BaseClient class to __DO SOMETHING__.
...program here...
Retrieved from "https://agileappscloud.info/aawiki-src/index.php?title=REST_API:document_Resource&oldid=14496"