Registering services with the Common REST API

The Common REST API receives data from services that are registered with RTCS. Although most services are registered automatically with RTCS, you can add a service to work with CRA by adding its key values to the configurations.json file. There are two ways to do this. You can add them using theCommon REST API, or you can add them manually. The configurations.json file is located in the installationDirectory/amiops/config directory of your CRA server.

Before you begin

Ensure that the CRA server is installed and running as described in Setting-up-the-Common-REST-API.

Registering a service using the update endpoint

You can use the update endpoint to update or add services to the configurations.json file. This method is recommended because it is less prone to inadvertent user errors.

To add a service using the update endpoint

Use a URL based on the following structure:

https://<hostName>:<portNumber>/cra/ServiceGateway/Services/<serviceName>/update?host=<serviceHostName>&port=<servicePortName>&description=<serviceDescription>

 The variables represent the following values:

• <hostName> is the name of the mainframe host where the CRA server is running.
• <portNumber> is the port number of the CRA server.
• <serviceName> is the name of the service you want to register.
• <serviceHostName> is the name of the mainframe host where the service you want to register resides.
• <servicePortName>is the port number of the service you want to register.
• <serviceDescription> is a description of the service.

HTTP status and reason codes

 The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

To update a service

Use the same URL structure as adding a new service. If the service is already in the file the API updates the service details in the file.

To delete a service

Use a URL based on the following structure:

https://<hostName>:<portNumber>/cra/ServiceGateway/Services/<serviceName>/delete

HTTP status and reason codes

 The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

Registering a service manually

The following example shows a configurations.json entry that manually registers an active MainView service named MVERESTAPI_SYSM_4412:

If you want to register more than one service, add a comma between the services, as displayed in the following example:

Use the following procedure to register a service manually.

To add a service manually

1. In an ASCII editor such as VI, open the configurations.json file, located in the installationDirectory/amiops/config directory of your CRA server.

2. Add a service object to the array and the following keys and values:
   
   

   Notes

   • Key names are case sensitive, so use the exact capitalization shown in the table.
   • If you include additional keys, the API ignores them.
   • You can enter the keys in any order.

   Key	Description
   HOSTIP	IP address of the service's target server
   STATUS	Indication of whether the service is active and ready for use This value must be set to ACTIVE for the service to be accessible to the API.
   PORT	Port that the service's target server uses
   WEBSERVICEName	The name you want to use for making API calls to this service
   TLS	Indication of whether the MainView server uses TLS authentication Valid values are Y for yes or N for no.
   TYPE	Type of service For MainView use MV.
   HOSTCN	Host of the service's target server
   DESCRIPTION	Description of the service