Cohesity takes an API-first approach to software design, meaning that all functions exposed in the web and cli-based user interfaces are serviced by REST API calls in the background. That means that anything that can be done in the UI can be done from any programming language that can send HTTP messages.
Why Use The Cohesity REST API?
- Infrastructure Orchestration: Customers have automated self-service workflows for provisioning new VMs and need a way to automatically add the new VM to a protection job and role-based access lists
- DevOps Orchestration: Customers want to automate the provisioning of database clones for test/dev environments
- Web Portal Integration: Customers want to execute Cohesity workflows from other service catalog portals like ServiceNow or vRealize Automation
Whatever the use case, the good news is that everything that can be done in the Cohesity UI can be done via the REST API.
PowerShell is an awesome language both for scripting but also interactive sessions which are great for demos as well as for interactive inspection of the objects returned by the REST API. The density and speed of code generation in PowerShell is I think unmatched by any other scripting language that I've come across.
Connecting to Cohesity (the hard way)
The first step in accessing the API is to authenticate with a Cohesity cluster and get an access token for use with subsequent API calls. As with any REST API call, we will need a header, body, and URL to construct our API call. In PowerShell, these will look like this:
You can see that the header specifies that we'll be sending and receiving JSON formatted data, and the body contains our credentials. We can then make our REST API call to get our access token:
As you can see, we received back an accessToken, tokenType, and a list of role-based access privileges granted to us by our login. We can then insert the tokenType and accessToken into our header, so that we can make authenticated API calls.Finally, we can set a new URL for our next API call, and get some real data from the Cohesity cluster. For example, we can get a list of protectionJobs:
Let's take a closer look at the first job in the list.
As you can see, we can extract all the details of the job.
You can see in the output above, that dates and times returned by the API are expressed in Unix Time (also known as POSIX time or UNIX Epoch time), usually in microseconds (since 00:00:00 Jan 1, 1970). In the example above, we can convert the creationTimeUsecs into a human-readable date in PowerShell like so:
and of course we can perform the conversion in the other direction:
OK, this is looking really complicated. I really don't want to be using a command like that in my day-to-day scripting. It's time to provide some functions to hide this kind of complexity.
Using a Function Library
Once I learned to do the basics as I've shown above, I developed a function library to make all these steps much easier. I built a number of functions and placed them in a file called cohesity-api.ps1 (we'll discuss this library in the next article).
To use the functions, we can source the library, then use its functions like so:
As you can see, we've eliminated all of the complicated steps of managing headers, URLs, and date conversions by wrapping all that code into functions in the library. Now we can stop wasting time fussing with the mechanics of API calls and spend more of our time doing what we came here to do: learn to exercise the Cohesity API itself.
Where To Go From Here
Now that we've got a simple way to access the Cohesity REST API, what can you do with it? Well there are several documentation resources at your disposal. First, there is the on-board Swagger page that's hosted on every Cohesity cluster. You can access page by clicking the REST API link at the bottom of the Cohesity UI. This link takes you to: https://<mycluster>/docs/restApiDocs/browse/
The swagger interface shows you that each API call has its own URL and which HTTP verb to use. If you click on one of the items, it will expand to show you the various parameters and even has a 'Try it out' button to make API calls right in the interface.
If you need more comprehensive documentation, every cluster hosts an API doc page:
and you can also find the API documentation on the Cohesity. com web site at:
I've written quite a few example scripts already. You can find them here:
I'll explain how I learned how to write these scripts in my next few articles. Coming soon!
The Cohesity Unofficial Function Library
Take a read of my next article: Cohesity Unofficial PowerShell Function Library to learn the easy way to use the Cohesity API...