Space banner

   

TEST - please delete me.

Reviewing and testing REST Web APIs

Representational State Transfer (REST) is only an architectural style and not a protocol. For example, there is no "official" standard for REST web services. However, it can use standards like HTTP, URI, XMS, and so on, like any standard.

The REST web API is a web service activated via a module in BMC Client Management using HTTP and a collection of resources, with four defined aspects:

  • the base URI for the web service, such as http(s)://localhost:1611/wsdoc.
  • the Internet media type of the data supported by the web service. This is often XML but can be any other valid Internet media type provided that it is a valid hypertext standard.
  • the set of operations supported by the web service using the HTTP methods GET, PUT, POST, and DELETE.
  • The API must be hypertext driven.

For more information about activating the web services module, see Configuring the web service.

The following HTTP methods are supported in BMC Client Management:

  • GET: List the URIs and perhaps other details of the collection's members if executed on a collection URI, or retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type if executed on an individual element.
  • POST: Create 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 not for execution on an individual element. If run on an individual element it treats the addressed member as a collection in its own right and creates a new entry in it.
  • PUT: Replace 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 it doesn't exist, creates it.
  • DELETE: Delete the entire collection or the addressed member of the collection.

BMC Client Management provides a tool to review and test the REST web API operations available for interaction with BMC Client Management database. It is divided in the following different sections:

  • Configuration: Configure the access to the BMC Client Management database.
  • Useful Information: Find more useful information about the Swagger online help tool as well as for the API operations.
  • Use Cases: Find use case examples for specific situations.
  • Summary of API Documentation: Provides access to all available operations via their groups.

Security in REST Web APIs

The REST API uses the JSON encoding. The API has no knowledge of the purpose it is going to be used for. It ensures only JSON encoding and returns data verbatim. As the 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.

The following are the use cases.

REST_API_usecases

To test the web service

  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.  In the Configuration box, enter the test server URI and credentials.

    (Click the screenshot to view it in higher resolution)


    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.

  3. Select the Show allowable values in snippet check box if it is not yet checked. A number of parameters require specific database values that you cannot be aware of. By selecting this check box, the list of possible values that can be entered into these parameters is provided with the snippet.
  4. Select the Open links as pop-up check box to open the the online help on return classes and snippets in a new pop-up windows. If clear, it opens in a new tab of the browser.
  5. To access the operations click the respective group link below the Summary of API Documentation bar and the available operations will be listed.

    (Click the screenshot to view it in higher resolution)

  6. To test an operation, enter the required data in the available boxes and then click Try it out!
    The operation zone is expanded enlarged and the new boxes show the result of the executed operation.

    (Click the screenshot to view it in higher resolution)

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