An Introduction to Catalogic ECX REST APIs Posted on Nov 1st, 2016 by Raghuram Devarakonda

Categories: DevOps, REST API

Rest APIs Catalogic

The days when an enterprise application can only be used from its user interface are over. These days, any application worth its salt needs to play well with other applications. This is especially true in the world of DevOps where your application is routinely expected to be able to be driven by APIs and other means.

In this regard, REST has become the dominant way by which APIs are exposed. You would be hard-pressed to find a service (cloud or on-premise) that doesn’t advertise REST API access to its functionality. Note that there are different interpretations on what exactly constitutes REST, but almost all these APIs have the following things in common:

  • Use http (or https) protocol.
    • Consistent use of http methods GET, PUT, POST, and DELETE
  • JSON as the data interchange format.

Catalogic ECX and REST APIs

Catalogic Software ECX provides many features that a modern datacenter needs. I am not going to delve deep into the feature set of ECX. There are other excellent resources if you want to know what ECX can do. Rather, I would like to talk about the fact that all the functionality of ECX can be accessed and controlled using REST APIs. This makes it a perfect fit in any workflow where automation is required. For example, an MSP may want to set up a protection policy when a customer provisions a Virtual Machine. They can do so using ECX APIs, thus integrating ECX in their tool chain.

All the examples in this post use the excellent curl utility, though you can use any other REST client (say, Postman) or even custom scripts written in any language. I would also assume at least some passing familiarity with REST concepts. Even if you don’t, the examples are simple enough that you can understand what is going on.

Also, I am going to pipe the output of curl command to “python -mjson.tool” like so:

$ curl ... | python -mjson.tool

This causes the JSON output to be pretty-formatted which is rather useful. If you try these examples on a Linux machine or where Python is available, you can do it the same way. In any case, I will not be showing the “python -mjson.tool” part in order to keep the commands simple.

Let us assume that ECX is accessible at https://1.2.3.4:8443 in the following examples.

Logging in to ECX

You first need to login to ECX before you can do any other operation. Here is how:

$ curl -X POST --user ':'
     -H "Accept: application/json" -H "Content-Type: application/json" 
     https://1.2.3.4:8443/api/endeavour/session 

200 OK

{
    ...
    "sessionid": "02da7d44638dc77c", 
    ...
    ...
}

If you are not very familiar with curl, here is a short explanation.

The HTTP method is passed with “-X” option. Here, you are using “POST”.
Request headers are passed using “-H” option. As you can see, we are setting the headers Accept and Content-Type to application/json.

For the sake of brevity, I will not be showing these two headers in the following commands but you need to pass them with every request. A useful trick is to add the following two lines to $HOME/.curlrc. curl will then automatically send these headers with every request.

-H "Accept: application/json"

-H "Content-Type: application/json"

You would pass user name and password with the option --user. ECX uses what is known as “HTTP basic authentication”.
And finally, the URL itself.
Also note that if you are using a self-signed certificate on ECX appliance, you will need to pass -k option to curl.

Assuming you passed the correct user name and password, the response will contain a field called “sessionid”. The value of this field is the token you need for using other APIs.

Managing Users in ECX

Now that we logged in, let us go ahead and invoke a few APIs. For example, here is how we can find list of users configured in the product. Notice how we are passing the token we received in the previous step.

$ curl -X GET -H "X-Endeavour-Sessionid: 02da7d44638dc77c" 
     https://1.2.3.4:8443/api/security/user

200 OK

{
   "users": [
        {
            "id": "1000", 
            "name": "admin",
            "permissions": [
                ...,
                ...
            ],
        }
    ],
    ...
}

The response shows that there is one user named “admin” in the system. Let us go ahead and create another user.

$ curl -X POST --data @- -H "X-Endeavour-Sessionid: 02da7d44638dc77c" 
     https://1.2.3.4:8443/api/security/user

{
    "name": "testuser",
    "password": "testpassword"
}

200 OK

{
    "name": "testuser",
    "id": "1001",
    "permissions": [
        ...,
        ...
    ],
    ...
}

Please note that I provided the bare minimum information necessary to create a user here. In reality, you would also need to specify some other information such as the permissions you want to give the user.

On a side note, since we needed to provide input data to POST request, I used the curl option --data @-which causes it to wait for data from STDIN. This way, I can just type in the data and press CTRL-D that will result in all the data to be sent in the request. An alternative way is to put the content in a file and then use the option --data @<FILE_NAME>.

Also, now that you know how to pass the session token, I will not be showing that in the following examples. This will make the examples simpler and more readable. Just bear in mind that the session token needs to be sent with every request.

Now that we created a new user, we should see two users listed when we do:

$ curl -X GET https://1.2.3.4:8443/api/security/user

Alternatively, if you want to get the information about the new user we just created, a slightly different URL is used (note the user ID at the end):

$ curl -X GET https://1.2.3.4:8443/api/security/user/1001

Moving on, here is how you can make changes to an existing user, say, to change the user name:

$ curl -X PUT --data @- https://1.2.3.4:8443/api/security/user/1001

{
    "name": "new name"
}

200 OK

{
    "name": "new name",
    "id": "1001",
    ...
}

As you can see, we use PUT method to update a resource.

Finally, let us go ahead and delete the user.

$ curl -X DELETE https://1.2.3.4:8443/api/security/user/1001

204 No Content

ECX follows the recommended REST practice of using the method POST to create a resource, PUT to modify, GET to view the details, and finally DELETE to delete the resource. The same pattern applies to all the other entities in ECX such as roles, resource pools, policies, and jobs to name a few.

HATEOAS

In addition to using HTTP methods in the recommended way, ECX implements another REST concept called HATEOAS where each response contains links to do further actions on that resource. Here is an example:

$ curl -X GET https://1.2.3.4:8443/api/security/user/1001

200 OK

{
    "name": "testuser",
    "id": "1001",
    "links": {
        "changePassword": {
            "href": "https://1.2.3.4:8443/api/security/user/1001?action=changePassword", 
            "rel": "action"
        }, 
        "edit": {
            "href": "https://1.2.3.4:8443/api/security/user/1001", 
            "rel": "update"
        }, 
        "self": {
            "href": "https://1.2.3.4:8443/api/security/user/1001", 
            "rel": "self"
        }, 
        "up": {
            "href": "https://1.2.3.4:8443/api/security/user", 
            "rel": "up"
        }
    }, 
    ...
}

As you can see, there are “links” that tell you how to do further actions on this particular user. For example, if you need to change password for this user, you would use the URL provided in “changePassword” section, which is:

https://1.2.3.4:8443/api/security/user/1000?action=changePassword

Conclusion

We have seen how ECX provides REST APIs that adhere to a well understood model. Using these APIs, you can drive ECX from your own scripts and applications, thus integrating it in your DevOps environment.

Arguably, I only covered at a very high level but hopefully it is enough to get you interested. Happy ECX exploring!

Raghuram Devarakonda is Principal Engineer, Research and Development, at Catalogic Software.