Difference between revisions of "Template:REST Resource"
imported>Aeric (→Fields) |
imported>Aeric (→Fields) |
||
(24 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
<noinclude> | |||
This template is intended for subclusion, to start an API definition: | |||
;Usage: <tt><nowiki>{{subst:REST Resource}}</nowiki></tt> | |||
---- | |||
</noinclude> | |||
Manage __resourceName__ (record)s using the [[REST API]]. | Manage __resourceName__ (record)s using the [[REST API]]. | ||
Line 4: | Line 9: | ||
{{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: | {{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 | # Add an entry to the categorized [[REST API]] page | ||
# Add an entry to the [[REST API]] | # Add an entry to the [[REST API:REST Resources (alphabetical)|alpha index]] | ||
# Add | # Add entries to the [[REST API:REST API CheatSheet|REST API CheatSheet]] | ||
}} | }} | ||
Line 14: | Line 19: | ||
===Permissions=== | ===Permissions=== | ||
'''''Check [[Administrative Permissions]] for a list of possibilities''''' | |||
{{PermissionRef|Access Control|use this resource.}} | |||
{{ | {{PermissionRef|User Management|use this resource.}} | ||
{{permissions| | {{permissions|Use Development Features|use this resource.}} | ||
{{ISV Configuration}} | |||
===List All __resourceName__ (Record)s=== | ===List/Get 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" 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 | |||
<blockquote> | |||
Use this URI to get a list of all __resourceName__ records, including all fields for each record: | |||
:<tt><nowiki>https://{domain}/networking/rest/__resourceName__?fieldList=*</nowiki></tt> | |||
To restrict the records returned or the fields returned, see the section that explains how to do a [[#Dynamic Search for __resourceName__ Records|Dynamic Search for __resourceName__ Records]] | |||
</blockquote> | |||
'''--OR--''' | |||
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__</nowiki></tt> | ;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__</nowiki></tt> | ||
Line 38: | Line 54: | ||
:<syntaxhighlight lang="xml" enclose="div"> | :<syntaxhighlight lang="xml" enclose="div"> | ||
<platform> | <platform> | ||
<__resourceName__> | |||
<id>...</id> | |||
<field>...</field> | |||
... | |||
</__resourceName__> | |||
<__resourceName__> | |||
... | |||
</__resourceName__> | |||
... | |||
<message> | |||
<code>0</code> | |||
<description>Success</description> | |||
</message> | |||
<recordCount>N</recordCount> <!-- Number of __ records returned --> | |||
</platform> | </platform> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 76: | Line 92: | ||
:<syntaxhighlight lang="xml" enclose="div"> | :<syntaxhighlight lang="xml" enclose="div"> | ||
<platform> | <platform> | ||
<__resourceName__> | |||
<id>...</id> | |||
<field>...</field> | |||
... | |||
</__resourceName__> | |||
<message> | |||
<code>0</code> | |||
<description>Success</description> | |||
</message> | |||
</platform> | </platform> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 100: | Line 116: | ||
:<syntaxhighlight lang="xml" enclose="div"> | :<syntaxhighlight lang="xml" enclose="div"> | ||
<platform> | <platform> | ||
<__resourceName__> | |||
<field>...</field> | |||
... | |||
</__resourceName__> | |||
</platform> | </platform> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 110: | Line 126: | ||
:<syntaxhighlight lang="xml" enclose="div"> | :<syntaxhighlight lang="xml" enclose="div"> | ||
<platform> | <platform> | ||
<message> | |||
<code>0</code> | |||
<description>Success</description> | |||
<id>...</id> <!-- ID of the newly created __resourceName__ --> | |||
</message> | |||
</platform> | </platform> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 128: | Line 144: | ||
:<syntaxhighlight lang="xml" enclose="div"> | :<syntaxhighlight lang="xml" enclose="div"> | ||
<platform> | <platform> | ||
<__resourceName__> | |||
<id>...</id> <!-- record ID --> | |||
... | |||
</__resourceName__> | |||
</platform> | </platform> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 138: | Line 154: | ||
:<syntaxhighlight lang="xml" enclose="div"> | :<syntaxhighlight lang="xml" enclose="div"> | ||
<platform> | <platform> | ||
<message> | |||
<code>0</code> | |||
<description>Success</description> | |||
</message> | |||
</platform> | </platform> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 156: | Line 172: | ||
:<syntaxhighlight lang="xml" enclose="div"> | :<syntaxhighlight lang="xml" enclose="div"> | ||
<platform> | <platform> | ||
<message> | |||
<code>0</code> | |||
<description>Success</description> | |||
</message> | |||
</platform> | </platform> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 174: | Line 190: | ||
:<syntaxhighlight lang="xml" enclose="div"> | :<syntaxhighlight lang="xml" enclose="div"> | ||
<platform> | <platform> | ||
.... | <__resourceName__> | ||
... | |||
</__resourceName__> | |||
... | |||
<message> | |||
<code>0</code> <!- The number of records returned --> | |||
<description>Success</description> | |||
</message> | |||
</platform> | </platform> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 189: | Line 208: | ||
! 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 || String || align="center"|Read Only || || || [[Record Id]] | ||
|- | |- | ||
| name || String || || align="center"|[[File:Checkmark.gif|link=]] || || | | name || String || || align="center"|[[File:Checkmark.gif|link=]] || || | ||
Line 197: | Line 216: | ||
| ...|| ... || ... || ... || ... || ... | | ...|| ... || ... || ... || ... || ... | ||
|- | |- | ||
| | | item || String || align="center"|Read Only || || description || AddlInfo | ||
|- | |- | ||
| | | item || String || || || description || AddlInfo | ||
|- | |- | ||
| | | item || String || || align="center"|[[File:Checkmark.gif|link=]] || description || AddlInfo | ||
|- | |- | ||
| | | item || String || align="center"|Writable on Add only || align="center"|[[File:Checkmark.gif|link=]] || description || AddlInfo | ||
|- | |- | ||
| | | structureItem || struct || || align="center"|[[File:Checkmark.gif|link=]] || structure (see below) || | ||
|- | |- | ||
| ...|| ... || ... || ... || ... || ... | | ...|| ... || ... || ... || ... || ... | ||
|- | |||
| colspan="6" bgcolor="Azure" style="height:7px" | <!-- SPACER ROW --> | |||
|- | |- | ||
| date_modified || Date || align="center"|Read Only || || || [[UTC Format]] | | date_modified || Date || align="center"|Read Only || || || [[UTC Format]] | ||
Line 221: | Line 246: | ||
! Name !! Type !! Attribute !! Default Value !! Description !! Additional Information | ! Name !! Type !! Attribute !! Default Value !! Description !! Additional Information | ||
|- | |- | ||
| | | item || String || align="center"|Read Only || Default || description || AddlInfo | ||
|- | |- | ||
| | | item || String || || Default || description || AddlInfo | ||
|- | |- | ||
| | | subItem || Tag|| || || description || AddlInfo | ||
|- | |- | ||
| ...|| ... || ... || ... || ... || ... | | ...|| ... || ... || ... || ... || ... | ||
|- | |||
| colspan="6" bgcolor="Azure" style="height:7px" | <!-- SPACER ROW --> | |||
|- | |- | ||
| date_modified || Date || align="center"|Read Only || || || [[UTC Format]] | | date_modified || Date || align="center"|Read Only || || || [[UTC Format]] | ||
Line 238: | Line 269: | ||
|} | |} | ||
== | ;structure Tag: | ||
:{| border="1" cellpadding="5" cellspacing="0" | |||
! Name!!Type!!Attribute!!Required on Add!!Description!!Additional Information | |||
|- | |||
| field || String || || || descr || addl info | |||
|} | |||
=== | ===Error Codes=== | ||
:{| border="1" cellpadding="5" cellspacing="0" | |||
! Platform Code||with Http Status||Description | |||
|- | |||
| align="center"| -7000 || BAD_REQUEST (400) || Invalid ID | |||
|} | |||
: | ''Learn more:'' | ||
:* See the [[REST API:Error Codes]] for common Http error codes | |||
:* See the [{{DOCHOST}}/javadocs/constant-values.html javadoc constants] for a complete list of <tt>PlatformException</tt> error-code constants. | |||
<!--ACTIVATE THE CATEGORY BELOW | <!--ACTIVATE THE CATEGORY BELOW | ||
<noinclude> | <noinclude> | ||
Line 335: | Line 293: | ||
</noinclude> | </noinclude> | ||
--> | --> | ||
Latest revision as of 01:13, 10 January 2015
This template is intended for subclusion, to start an API definition:
- Usage
- {{subst:REST Resource}}
Manage __resourceName__ (record)s using the REST API.
- Learn more: REST API Conventions and Considerations.
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:- Add an entry to the categorized REST API page
- Add an entry to the alpha index
- Add entries to the REST API CheatSheet
Requirements
- Requirement #1
- Requirement #2
Permissions
Check Administrative Permissions for a list of possibilities
Users that have the Access Control permission can use this resource..
Users that have the User Management permission can use this resource..
Users that have the Use Development Features permission can use this resource.
- This configuration option is managed by a Service Provider platform admin.
List/Get 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
Use this URI to get a list of all __resourceName__ records, including all fields for each record:
- https://{domain}/networking/rest/__resourceName__?fieldList=*
To restrict the records returned or the fields returned, see the section that explains how to do a Dynamic Search for __resourceName__ Records
--OR--
- 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>...</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>...</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>...</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>...</id> <!-- record 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
- For more examples, see Filter Expressions in REST APIs and the REST API Examples.)
- 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)
- sortBy - Field name for primary sort
- For more information, see: Specifying Query Parameters in REST APIs
- Response
<platform> <__resourceName__> ... </__resourceName__> ... <message> <code>0</code> <!- The number of records returned --> <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 description String ... ... ... ... ... ... item String Read Only description AddlInfo item String description AddlInfo item String description AddlInfo item String Writable on Add only description AddlInfo structureItem struct structure (see below) ... ... ... ... ... ... 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 item String Read Only Default description AddlInfo item String Default description AddlInfo subItem Tag 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
- structure Tag
Name Type Attribute Required on Add Description Additional Information field String descr addl info
Error Codes
Platform Code with Http Status Description -7000 BAD_REQUEST (400) Invalid ID
Learn more:
- See the REST API:Error Codes for common Http error codes
- See the javadoc constants for a complete list of PlatformException error-code constants.