Difference between revisions of "REST API:translationWorkbench 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]].
Get translated strings 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===
===Requirements===
:* Requirement #1
:* Translations have been created in the [[Translation Workbench]]
:* 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.)


===Get a Translation for a Custom Label===
;Method:GET
;Method:GET
;URI:<tt><nowiki>https://{domain}/networking/rest/__resourceName__</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:
:<syntaxhighlight lang="xml" enclose="div">
<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]]
;URI:
:<tt>{{platformURL}}/rest/translationWorkBench/customlabel/{key}</tt>
:<tt>{{platformURL}}/rest/translationWorkBench/customlabel/{key}?args=param1,...</tt>
:where:
::* '''{key}''' - The index value used to look up a translated string, in the formΒ  <tt>{category}.{token_id}</tt>


===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|
{{Query Parameters|
:Introductory sentence, if any
::*<tt>args</tt> - A list of one or more arguments that will be interpolated into the string at the locations assigned to them when the base string was created.}}
::*<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:
;Response:
:When the user's language is Spanish, this sample response comes in reply to the request:
::<tt>{{platformURL}}/rest/translationWorkBench/customlabel/validation.record_deleted?args=5</tt>
:<syntaxhighlight lang="xml" enclose="div">
:<syntaxhighlight lang="xml" enclose="div">
<platform>
<platform>
Β Β  Β  <message>
Β Β  Β  <translationWorkBench>
Β Β  Β  Β  Β  <code>0</code>
Β Β  Β  Β  Β  <key>validation.record_deleted</key>
Β Β  Β  Β  Β  <description>Success</description>
Β Β  Β  Β  Β  <translatedText>5 registros eliminados con Γ©xito</translatedText>
Β Β  Β  </message>
Β Β  Β  </translationWorkBench>
</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>
Β Β  Β  <message>
Β Β  Β  Β  Β  <code>0</code>
Β Β  Β  Β  Β  <code>0</code>
Line 185: Line 38:


===Fields===
===Fields===
:''Note:'' Unless otherwise indicated, the attribute for a field is "Editable on Add or Update".
:{| border="1" cellpadding="5" cellspacing="0"
:{| border="1" cellpadding="5" cellspacing="0"
! Name!!Type!!Attribute!!Required on Add!!Description!!Additional Information
! Name!!Type!!Description
|-
| id || String || align="center"|Read Only || || || [[Record Identifier]]
|-
| 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
| key || String || The ID of the translated element, in the form <tt>{category}.{token_id}</tt>. For example: <tt>validation.record_deleted</tt>
|-
|-
| ...|| ... || ... || ... || ... || ...
| translatedText || String || The translation for the key, in the current user's language, with any arguments in the request interpolated into the string.
|-
| ...|| ... || ... || ... || ... || ...
|-
| 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|translationWorkbench Resource]]
</noinclude>
</noinclude>
-->

Latest revision as of 21:47, 30 March 2012

Get translated strings using the REST API.

Learn more: REST API Conventions and Considerations.

Requirements

Get a Translation for a Custom Label

Method
GET
URI
https://{yourDomain}/networking/rest/translationWorkBench/customlabel/{key}
https://{yourDomain}/networking/rest/translationWorkBench/customlabel/{key}?args=param1,...
where:
  • {key} - The index value used to look up a translated string, in the form {category}.{token_id}
Query Parameters
  • args - A list of one or more arguments that will be interpolated into the string at the locations assigned to them when the base string was created.
For more information, see: Specifying Query Parameters in REST APIs
Response
When the user's language is Spanish, this sample response comes in reply to the request:
https://{yourDomain}/networking/rest/translationWorkBench/customlabel/validation.record_deleted?args=5
<platform>
    <translationWorkBench>
        <key>validation.record_deleted</key>
        <translatedText>5 registros eliminados con Γ©xito</translatedText>
    </translationWorkBench>

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

Fields

Name Type Description
key String The ID of the translated element, in the form {category}.{token_id}. For example: validation.record_deleted
translatedText String The translation for the key, in the current user's language, with any arguments in the request interpolated into the string.