REST API requests use encoding for characters that a browser can misinterpret. The following example uses hexadecimal encoding in the body of the REST API request to rename a folder to a new path in the default volume:

Always encode characters that have a specific meaning in a URI when you use them in other ways. An ampersand introduces a parameter in a URI, so you must encode an ampersand that appears in a value string. For example, use:

instead of:

Table 15‑1 describes the available character substitutions.

All Actuate REST API resources except POST login use the authId URL parameter. All Actuate REST API resources use locale and targetVolume URL parameters. The HTTP header for all Actuate REST API resources provides equivalent fields for these parameters. To avoid re-use of URLs to access iHub information, use the HTTP header fields rather than URL parameters to send these values to iHub.

The AuthId header field is equivalent to the authId URL parameter. In any request, you can set the value of the AuthId field in the HTTP header to the AuthId value returned by the POST login resource.

The Locale header field is equivalent to the locale URL parameter. The locale value specifies a locale code, assigning a language and country to format values to match localized conventions. The format of the locale value is a two-letter language code and a two‑letter country code separated by an underscore. The default value is set in the constants.js configuration file. Java defines the language and country codes.

The TargetVolume header field is equivalent to the targetVolume URL parameter. The target volume value sets the name of the iHub volume to which to make requests. The default value is set in the constants.js configuration file.

REST API requests that return a list of resources from iHub, such as /files,
/folders, /jobs, /bookmarks, /users, or /usergroups, accept a search query parameter. The search value limits the results to those resources with a name that matches the specific search value. To search for names with a substring or character, use wildcard characters. For example, a search value of 'ab*' returns a resource with the name absolutevalues but not resources with the names databank or bankstatements.

Privileges control the visibility and actions available to users for specific files and folders. By default, all privileges are denied. To grant privileges, a user or user group must appear in the access control list (ACL) for a file or folder. The privileges granted are listed in the Permission property of the ACL. Available privileges are Delete, Execute, Grant, Read, Secure Read, View, and Write. The Administrator user and Administrators user group have all privileges for every file and folder in the volume, even though the Administrator user and Administrators user group do not appear in every ACL. Every user is a member of the All user group. If the All user group provides access to a file or folder in a volume, every user of that volume receives that access.

All REST API requests respond with a standard set of HTTP response codes that identify the results of the request. The standard set of response codes for the Actuate REST API are as follows:

The body of the response includes more information in the case of an error. For example, the following response is for a GET folders/{folderId} request that specifies a non-existent identifier:

REST API requests that return a list of resources from iHub, such as /files,
/folders, /jobs, /users, or /usergroups, accept a fetchSize query parameter that limits the number of items to return at one time. When fetchSize is not specified, lists return the number of entries set in the FETCHSIZE configuration parameter in the constants.js configuration file. The number of items found is available from the TotalCount field in the response object. When the TotalCount exceeds the fetchSize, the response object also includes a fetchHandle field that provides access to the next set of data from the returned list. For example, if fetchSize is set to 1, and the total number of users found is 28, a GET users request using a fetchSize of 1 returns the following response object:

To request the next user from the list, use a second request for users and include the fetchHandle as the only query parameter in the request, similar to the following:

The response includes another fetchHandle for the next set from the list. You can iterate through the list using fetchHandle in one direction. If fetchDirection is set, the list order applies to all the results. You cannot change the value of fetchDirection to go backwards through a list.

The REST service for the REST API runs in HTTP mode by default. To enable HTTPS support, edit the constants.js configuration file and change the value of the USEHTTPS parameter to true. You must restart the REST server service to commit the changes. By default, the REST service responds to HTTPS requests on port 5010. Configure the port using constants.js, as described in Configuring the REST API using constants.js.

Use System Console to stop and start the REST service that runs on iHub. If System Console is not installed, stop and start the iHub itself to stop and start the REST service.

If the REST service is deployed on a different machine, open a command window and navigate to the RESTAPI\server folder. To start the REST service, type the following command and press Enter:

To stop the service, press Ctrl+C.

You can configure the behavior of REST API resources by editing the constants.js configuration file. Constants.js is installed with iHub in the following path:

For REST API deployed separately from iHub, constants.js is located in the following path:

Table 15‑2 lists and describes the parameters in the constants.js configuration file.