REST API:exec Resource

From AgileApps Support Wiki


Provides the ability to execute a class method using the REST API.

Considerations
  • A Class must be defined. (The exec resource invokes a method in the class.)
  • An instance of the class is created automatically, so the method need not be static.
  • Whether passed in XML or JSON, parameters passed to the method in the <execClass> segment must consist of a flat structure, as in the example that follows. (The structure is converted to a HashMap, so it cannot contain any complex elements or attributes.)
  • Signatures:
    • The method must be public
    • The method can take no arguments: public methodName()
    • Or it take arguments passed in a Map: public methodName(Map params)
      (Parameters passed in the REST request shown below are wrapped in a Map, and passed to the method.)
  • Return Types:
    • A method may return void.
    • If the return type is a Map, it can be used to return multiple key-value pairs.
    • Any other return is automatically converted to a String, using Object.toString(). The string value is returned with key = result.
Method
POST
URI
https://{yourDomain}/networking/rest/class/operation/exec
Request
<platform>
    <execClass>
        <clazz>com.platform.yourCompany.yourApplication</clazz>
        <method>methodName</method>
        ...optional list of additional parameters like these...
        <firstName>Peter</firstName>
        <lastName>Smith</lastname>
    </execClass>
</platform>
(Note that the items in the <execClass> tag form a flat structure.)
Response
For a method that returns a Map, the returned structure looks like this:
<platform>
    <execClass>
        <clazz>com.platform.yourCompany.yourApplication</clazz>
        <method>methodName</method>
        <key1>value1</key1>
        <key2>value2</key2>
         ...
    </execClass>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
For a method that returns anything else, the returned structure looks like this:
<platform>
    <execClass>
        <clazz>com.platform.yourCompany.yourApplication</clazz>
        <method>methodName</method>
        <result>...value returned from the method...</result>
    </execClass>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>
In either case, a JSON response will have the same structure, but in JSON format.
Known issue
Null return values are not handled at this time.