Reviewing and testing REST Web APIs

Security in REST Web APIs

A REST Web API uses the JSON encoding. The API has no knowledge of the purpose it is going to be used for. It ensures JSON encoding and returns data verbatim. As this data can be used for different purposes, we recommend that you encode the data either before sending it to the API or after collecting it from the API to ensure security.

The following are the use cases for REST Web APIs:

To authenticate using a token or the bearer scheme

Using the standard HTTP basic authentication mechanism, you must provide the user credentials for each call which can disclose the information when the connection is not secure. To secure the information, you can invoke a preliminary web service to get an authentication token. The HTTP bearer scheme uses this token for the subsequent calls. 

The preliminary web service does not need authentication but it needs the user credentials in the PUT request. The BMC Client Management Web API module then verifies the supplied credentials and delivers an authentication token specific to the administrator. Subsequent calls that use this bearer token are identified as calls from the same administrator.

The following preliminary web service is called to get the authentication token:

Example:

$ curl -k -X PUT -d '{"login":"admin","password":"xxx"}' https://sop-ctruc-02:1616/api/1/admin/session

{"SessionId":"fd18fe69-7732-66ee-8e53-23039c393ccf","ErrorCode":0}

The session ID returned in the response is used to authenticate the subsequent calls by using the HTTP bearer scheme. Using this token has the same effect as authenticating by using the credentials above.

To acquire the bearer token, using the Swagger interface, call the session web service from the admin section.

Below is a sample call. 

To test the web service

BMC Client Management provides a tool to review and test the REST web API operations available for interaction with the BMC Client Management database. 

1. In a browser window, enter the tool URI in the https://server:port/wsdoc format. For example,http://scotty:1611 or http://localhost:1611.

2. Click Authorize. The Available authorizations window is displayed.

   

3. In the Available authorizations window, enter the user name and password and click Authorize. If you are using the HTTP Bearer Scheme mechanism, enter the authorization token. 

   The access to the BMC Client Management database is now granted.

   Note

   If your credentials contain domain name, enter the credentials in the following format: [domain]\\[username] (with two '\'). For example,production\\administrator.

4. To access the operations, click the respective group link. The available operations are listed.
   

   Click the screenshot to view it in higher resolution.

5. To test an operation, click Try it out.
   All the fields are enabled for editing. 
6. Change the values of the required fields and click Execute. 
   
   The test result is displayed.
   
7. Click Clear if you want to clear the data and start the test again.

For more information about supported REST web services operations, download and see the BMC Client Management - Web Services Operations Manual for Integration with BMC Client Management.