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 the Common REST API, or you can add them manually. The configurations.json file is located in the USS directory of your CRA server.

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.

The update endpoint uses the POST method to update or add a service.

Use a URL based on the following structure:

https://<hostName>:<portNumber>/cra/serviceGateway/services/<serviceName>/update?host=<serviceHostName>&port=<servicePortName>

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>&ip=<ipAddress>

The variables represent the following values:

Variable	Description
<serviceName>	(Required) Name of the service you want to register
<hostName>	(Required) Name of the mainframe host where the CRA server is running
<portNumber>	(Required) Port number of the CRA server
<serviceHostName>	Name of the mainframe host where the service you want to register resides
<servicePortName>	Port number of the service you want to register
<serviceDescription>	Description of the service
<ipAddress>	IP address of the CRA server

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.

Error Code	Explanation
200	Successful completion
400	Service registered via RTCS and cannot be edited
404	The path is not valid.
500	Failed to edit the configuration.json file

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

The delete endpoint uses the DELETE method 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.

Error Code	Explanation
200	Successful completion
400	Service registered via RTCS and cannot be deleted
404	The path is not valid.
500	Failed to edit the configuration.json file

Registering a service manually

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

[
{
        "HOSTIP": "123.12.23.123",
        "STATUS": "ACTIVE",
        "PORT": 4412,
        "WEBSERVICEName": "MVERESTAPI_SYSM_4412",
        "TLS": "N",
        "TYPE": "MV",
        "HOSTCN": "myHost",
        "DESCRIPTION": "My AMI Ops Server"
}
]

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

[
{
        "HOSTIP": "111.11.11.111",
        ...
"HOSTCN": "myHost1"
},
{
        "HOSTIP": "222.22.22.222",
        ...
"HOSTCN": "myHost2"
}
]

Warning

In the configurations.json file, make sure that no characters (including nonprinting characters) appear after the closing brace ( } ) of the last service listed in the file. Any character that appears after the closing brace can cause the API to stop functioning.

Use the following procedure to register a service manually.

To add a service manually

Important

The configurations.json file is ASCII-encoded and requires an ASCII editor such as VI.

In an ASCII editor such as VI, open the configurations.json file, located in the installed USS directory of your CRA server.

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

Important

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 BMC AMI Ops server uses TLS authentication Valid values are Y for yes or N for no.
TYPE	Type of service For BMC AMI Ops use MV.
HOSTCN	Host of the service's target server
DESCRIPTION	Description of the service

Registering services with the Common REST API

Registering a service using the update endpoint

To add a service using the update endpoint

HTTP status and reason codes

To update a service

To delete a service

Registering a service manually

To add a service manually

On this page