Cohesity DataPlatform provides a intuitive browser-based UI to manage and monitor the cluster. Our UI receives accolades from the customers for its contemporary look and feel, and intuitive ease of use. The UI relies on the Cohesity REST API implementation built into DataPlatform to achieve all of its functionalities. The Cohesity REST APIs are fully available to system administrators.via native documentation that resides on the cluster itself. Customers can use the APIs to integrate with their existing management tools, or develop their own scripts to automate their most common workflows. In this introductory post, we explain how to access the REST API documentation on DataPlatform, and how to get started with simple tasks such as user authentication.
REST API Documentation
There are two types of documentation provided on the Cluster. One is interactive page which provides live interaction to the Cluster for developers who want to gain hands-on experience on the REST APIs before start developing. Other type is static page and provided as a reference document.
Both of them are always available in UI after logging into the Cluster. At the top right corner of any UI page, if you click on Help, it pulls down a menu showing REST API. If you click on REST API, it opens the interactive documentation page on a separate tab.
Getting Hands-on Experience
On the new tab, entire interactive REST API documentation page is shown. APIs are grouped by the entity they manage. Each group is marked by colored tabs on top of the page. Developers can jump to the group they are interested in by clicking the corresponding tab. Each tab lists the resources by Paths and the REST methods for accessing them. Each method is explained with a Summary and a Description. It may have optional Parameters section. If there is a parameter section, it lists all the parameters that can be passed in the request. For each parameter, specifies its type, an indication whether the parameter is required or optional, and a description of the parameter. Required members of an object are marked with a red star on the right.
Following the Parameters section, there is a Responses section. This section lists the Success Response and the Error Response with Status Code. At the end of each API there is a “Try this Operation” button which provides interactive experience to the developers. Let us see how this cool feature can be used to get a hands-on experience on all APIs.
Authenticating to the Cluster
First thing that should be done in any automated workflow is to authenticate to the Cluster and get an access token.
That token is used in all the subsequent requests. Now let us see how to get the token interactively. When the “Try this operation” button is clicked, it shows a form to fill up the parameters to be passed in the request sent to the Cluster. It indicates the required parameters for the request. Developers fill in the form as follows.
As the developer enters the values, the interactive page forms the JSON body for the request. Once the required parameters are filled, the request can be sent using the “Send Request” button. The JSON body and request URL are shown below.
When the “Send Request” is pressed, it sends the REST request to the Cluster and gets the response back. The Response displayed on the interactive page is shown below.
Thus the interactive page shows how the request should be built and what to expect in the Response. This is particularly useful for developers who want to learn Cohesity REST APIs and develop programs to automate workflows. This can be used as a debugging tool and cut the development cycle. This gives insight into various functionalities of the Cohesity DataPlatform and helps better understanding of the regular manual and the UI.
Language Independent
Since Cohesity REST API supports JSON body over http protocol, any programming language that has support for JSON and http can be used for developing workflow automation. Python, Java, and Shell scripts can be used for this purpose.
The knowledge we gained from the hands-on experience using the interactive documentation page can be put to use immediately. Developing shell scripts using curl commands are very easy. The shell script getAccessToken.sh given above demonstrates the same thing what we did using the interactive documentation page. When the script is run, it gives the following output.
In the above script, the use of POST method is demonstrated. As a continuation of that script, we give more GET method examples. The important thing to notice is how the access token is used in the requests. We are not giving the output for lack of space in this post. We will cover PUT and DELETE methods in the future posts.
Reference Documentation
On the top of the interactive REST API page, there is a link to the static reference documentation page marked here.
When the link is clicked, the static reference document page is opened on a separate tab. It is shown below. Same list of APIs in the interactive page are also listed in this page under Summary.
Each http method and the resource name combination has a hyperlink. When the link is clicked, it shows the documentation for that method. It describes the API in details and hyperlinks to the Request body and Responses.
Conclusion
In this post, we introduced two types of Cohesity REST APIs documentations, interactive and reference pages. We explained how to get hands-on experience using the interactive page. We demonstrated how to apply that experience to write simple scripts to start using the APIs. In Future blogs we will cover some of the most frequently used workflows and how to automate them. Please send us your feedback and let us know if you are interested in any specific workflow.
