This blog entry describes how you can retrieve a description file (in JSON or YAML) of the Spectrum Scale REST API 4.2.3 and how you can use this description file to generate client code using
editor.swagger.io. If you haven't heard of swagger yet, it describes itself as:
Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
The Spectrum Scale REST API is based on this framework. The main reason for choosing swagger is that it's a very wide-spread framework build on the OpenAPI Specification (OAS) and that client code for almost 40 different languages can be generated very easily using a Swagger description file:
Using the Spectrum Scale REST API
You can skip this section if you are already familiar with accessing the Spectrum Scale REST API. If not it's good to know that in 4.2.3 the architecture has changed slightly and that the REST API is now delivered as part of the Spectrum Scale GUI. This means that after you've installed and initialized the Spectrum Scale GUI server you are ready to use the REST API. You can use the following curl command to check if everything is in place and to display all of the available operations and endpoints:
curl -k -u admin:admin001 -X GET -H content-type:application/json -H accept:application/json "https://localhost:443/scalemgmt/v2/info"
Displaying the Spectrum Scale REST API documentation
To display a swagger-like documentation you can access the following page in your browser replacing [guiHost] with the hostname of your Spectrum Scale GUI server:
https://[guiHost]:443/ibm/api/explorer/
The following screenshot shows the entry point of the documentation. You can click on "Spectrum Scale REST API v2" to view the documentation of all the available operations and endpoints:
Here's an example of the documentation for the GET operation on the endpoint "/scalemgmt/v2/filesystems/{filesystemName}/filesets" which will return all the filesets for the specified filesystem:
As you can see all the attributes (and data types) of the returned object are listed. Feel free to take a look at all the other endpoints. There's a lot to discover.
Retrieving the Spectrum Scale REST API description file for Swagger
Let's get started with generating client code! The first thing you need is to retrieve the Swagger API description file which can either be in YAML or JSON format. The Swagger Editor supports both formats. Such a description file describes the API formally in a machine-readable format with all the attributes, operations and endpoints. The documentation that can be seen above is generated out of such a description file. The Swagger Editor can either be used to create a new API or to upload an existing one, which is exactly what we need. To retrieve the description file for the Spectrum Scale REST API you need to access the following URL:
https://[guiHost]:443/ibm/api/docs?root=/scalemgmt/v2/
You should see the following screen:
To download that description file you can simply click on "Save" and save the file on your local disk for example as "spectrum_scale_rest_api_423.json".
The next step is to upload this file to the Swagger Editor. After accessing
editor.swagger.io navigate to "File" > "Import File" and choose the JSON file you've just saved.
After uploading the JSON file you should see the content of the description file on the left side and the generated documentation on the right side:
To generate a client you can simply click on "Generate Client" and select one of the displayed languages. The result is a ZIP file which contains generated code that can be used to develop your first REST API client.