Logging in to a service using the Common REST API

To retrieve data from a service using Common REST API , you must log in to the service.

Before you begin

Log in to the service from which you want to retrieve data, or follow these steps to obtain a list of services that are registered to work with the API. If you already know the name of the service to which you want to log in, you can skip this procedure.

Execute the following GET command:
https://<hostName>:<portNumber>/cra/ServiceGateway/Services

In curl, the URL resembles the following example: 
curl http://localhost:8080/cra/ServiceGateway/Services

The Services request returns a JSON file listing the registered services. In the following example, the ellipsis at the end indicates that the returned JSON might include additional entries of this structure:

[
    {
        "HOSTIP": "172.11.11.123",
        "STATUS": "ACTIVE",
        "PORT": "22101",
        "WEBSERVICEName": "MVERESTAPI_SYSX_22101",
        "TLS": "N",
        "TYPE": "MV",
        "HOSTCN": "SYSX"
    },
    {
        "HOSTIP": "172.11.11.123",
        "STATUS": "ACTIVE",
        "PORT": "4411",
       "WEBSERVICEName": "MVERESTAPI_SYSX_4411",
        "TLS": "Y",
        "TYPE": "MV",
        "HOSTCN": "SYSX"
    },
    ...
]

To log in to a BMC AMI Ops service

1. Use the following URL to log in to a service using the API:
   https://<hostName>:<portNumber>/cra/ServiceGateway/Services/<serviceName>/Logon
   The placeholders in the URL are defined as follows:
   
   • <hostName> is the name of the mainframe host where the Tomcat server is running.
   • <portNumber> is the port number of the Tomcat server.
   • <serviceName> is the name of the registered service. For example, in the example JSON code shown above, the name of the first registered service is MVERESTAPI_SYSX_22101.
2. Set up an HTTP request:
   1. In the Header, set the Content-Type to application/x-www-form-urlencoded.
   2. Set Username and Password to your mainframe user credentials for accessing Tomcat. This user must have the required SAF permission defined.
   3. Use an SSL certificate to connect to your MainView host server, or in the Body, set the following keys:
      • username=<userName>
      • password=<password>
      Replace <userName> and <password> with your credentials for logging into the MainView service. This user must have permission to access the data. This user does not require the SAF permission that is required for accessing Tomcat (unless it is the same user).

3. Issue the Logon request.

The API returns a 32-character user token: 

{
	"userToken": "38651614-99ca-4ec8-90ce-334475abc0f4"
}

Until you log out or the token expires. you must pass this token in all subsequent requests from the selected service.
For example:

curl -H 'Accept: application/json' -H "Authorization: Bearer 38651614-99ca-4ec8-90ce-334475abc0f4" https://<hostName>:<portNumber>/cra/ServiceGateway/Services/<serviceName>/products/<productName>/views