Overview

InCenter provides the ability for custom software running on an external computer to communicate with the InCenter server using a predefined REST API. The REST API supports full system configuration and administrative operations.

The API itself is documented in a separate REST API Guide which is provided as part of each InCenter release.

Like normal SSH access, InCenter access using the REST API requires authentication with the credentials of a User object. Setting up users is described in Chapter 9, Managing Users.

Changing REST API Properties

It is possible to customize the parameters for REST access using the CLI. By default, access to the InCenter server using the REST API is enabled. It can be disabled using the following command sequence:

admin@InCenter:/> cc Settings  
admin@InCenter:/Settings> set REST Enabled=No

This CLI set command above could have included any of the following command parameters to change REST API access properties:

Note that the port number used for REST API access is always 8443 and this cannot be changed.

The IP address used for connection by the API (either IPv4 or IPv6) is the same as the standard InCenter management IP and this is displayed on the console after InCenter startup.

The SessionTimeout is how long the session token that the client receives from InCenter will be valid. The default time is 20 minutes. The minimum value possible is 1 minute.

Replacing the Default REST API Certificate

After initial startup of the InCenter server, a default REST API certificate called rest_server is automatically used when serving HTTPS requests.

The certificate used for the REST API can be changed by first uploading new certificate files to InCenter's root directory using an SCP or SFTP client on an external computer. For example:

$ scp my_cert.cer admin@192.0.2.10: 
$ scp my_cert.key admin@192.0.2.10:

The CLI can then be used to change the default files:

admin@InCenter:/> cc Settings  
admin@InCenter:/Settings> set REST CertificateData=my_cert.cer 
admin@InCenter:/Settings> set REST CertificateKey=my_cert.key

Missing Activation Response After a Certificate Change

Regardless of how the REST API certificate is changed (it can be achieved using the CLI as above or using the REST API itself), if the user activates this configuration change with the REST API, there will be no response from the InCenter server. It is only when the subsequent commit action is performed that the activate operation can be confirmed.

If the REST activate was successful then the subsequent commit operation will also be successful. If the activate was not successful then the commit will return a message saying that an activate must be performed first.