Accessing the IBM Storage Scale REST API endpoint details through Swagger and API explorer

You can access the details of the API endpoints through the following three options:

  • Swagger editor.
  • API explorer option that is available on the GUI node.
  • IBM Storage Scale Documentation.

The Swagger option is widely used because you can view the descriptions, run the API endpoints with the required parameters, and generate client code.

Accessing API details by using swagger

The Swagger editor uses the API description file, which can be either in YAML or JSON format. Such a description file describes the API formally in a machine-readable format with all the attributes, operations and endpoints. You can get the API description from the GUI node.

The following steps help you to access the API details and try out the endpoints by using the Swagger editor:

  1. Retrieve the description file for the IBM Storage Scale management API from the following location: https://[host name or IP address of the GUI server]:443/api/docs?root=/scalemgmt/v2/. The following screen appears.
    Figure 1. Option to download API description files in JSON format from the GUI node
    Option to download API description files in JSON format from the GUI node
  2. Click Save and save the description file in the JSON format.
    Note: If you are using Chrome or Microsoft Edge, you must right-click the browser page and select Save as from the menu that appears to save your file in the JSON format.
  3. Go to http://editor.swagger.io/ to open the Swagger editor in the web browser.
  4. In the File menu, select Import file and then browse and select the JSON file that you downloaded.

    You can now see the content of the description file on the left side and the generated documentation on the right side as shown in the following figure:

    Figure 2. REST API documentation opened in Swagger editor
    REST API documentation opened in Swagger editor

The left side of the view provides the code. The right side of the view displays all the endpoints with their input and output parameters. It also provides the option to try out the code by using Curl. The following topics provide details about the request parameters, response, and status of the request:

The following steps explain how to work with the endpoints in the Swagger editor:

  1. Open Swagger editor and import the description file as explained before. You can see the content of the description file on the left side and the generated documentation on the right side.
  2. Click Authorize and enter your user credentials that you use to access the GUI node.
  3. Click the endpoint that you want to explore or try out, from the list of endpoints. The endpoint details appear. Each endpoint provides the details such as the list of request parameters, option to try out the parameters, and response data that includes the requested information and endpoint execution status. The following figure shows the options that are available in the GET /scalemgmt/v2/ces/services/{service} endpoint.
    Figure 3. Example for options that are available in the Swagger editor for each endpoint
    Example for options that are available in the Swagger editor for each endpoint.
  4. Type the name of the service for which you need the details, in the Parameters section. In this example, SMB is selected as the target service.
  5. Click Execute to view the details of the specified service.
The Responses section displays the following details:
  • Curl command that is run in the background. For example, curl -X GET "http://198.51.100.12:1000/scalemgmt/v2/ces/services/smb" -H "accept: application/json" -H "authorization: Basic YWRtaW46YWRtaW4wMDE=
  • Request URL. In this case, it is http://198.51.100.12:1000/scalemgmt/v2/ces/services/smb
  • Response data: The response data includes the status of the request and the requested data in a GET request.

Generating client code from Swagger

To generate the client code from the Swagger editor, click Generate Client and select the format in which you need to generate the client code. You can use it to develop the client application that uses the IBM Storage Scale API endpoints.

Accessing API details from GUI node by using the API explorer

To display a swagger-like documentation, you can access the following page in your browser: 
https://[guiHost]:443/api/explorer/

Where, [guiHost] is the host name or IP address of the IBM Storage Scale GUI server.

The options that are available to view the endpoint details or try it out, are the same as the ones that are available in the Swagger editor. When you use the API explorer that is available on the GUI node, you do not need to separately import the JSON file that contains the API endpoint descriptions.

Accessing API documentation through the IBM Storage Scale Documentation

To access the details of each endpoint from the IBM Storage Scale Documentation, see IBM Storage Scale management API endpoints