Reviewing and testing REST Web APIs

The following HTTP methods are supported in BMC Client Management:

  • GET: Lists the URIs and perhaps other details of the collection's members if executed on a collection URI. If executed on an individual element, retrieves a representation  of the addressed member of the collection expressed in an appropriate internet media type.
  • POST: Creates a new entry in the collection. The new entry's URI is assigned automatically and is usually returned by the operation. This method is mainly used on a collection URI that is not for execution on an individual element. If run on an individual element, it treats the addressed member as a collection and creates a new entry in it.
  • PUT: Replaces the entire collection with another collection if executed on a collection URI. If executed on an individual element, it replaces the addressed member of the collection, or if the addressed member of the collection doesn't exist, creates it.
  • DELETE: Deletes the entire collection or the addressed member of the collection.

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:

REST_API_usecases

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:

HTTP methodPUT
HTTP URI/api/1/admin/session
HTTP bodyJSON content with two string based parameters: login and password

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.

Important

This token expires after a few minutes of inactivity. The default value is 5 minutes. You can configure this value by changing the Auto logout delay (sec) value set in Console appearance and general preferences.

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

Below is a sample call. 

We recommend that you use the secured connections (HTTPS) irrespective of the selected authentication mechanism.

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 AuthorizeThe 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.

Was this page helpful? Yes No Submitting... Thank you

Comments