Playing with REST API

Overview

In this article, I will describe how REST API works natively in Red Hat CloudForms.

REST stands for Representational State Transfer. REST is a web standard based architecture and uses HTTP protocol for data communication. It revolves around resources where every component is a resource and is accessed by a common interface using HTTP standards method.  

Red Hat CloudForms provides APIs to integrate external systems and initiate provisioning via CloudForms. In CloudForms, REST can be accessed by adding “/api” prefix to the URL.  

 

https://<IP or hostname of appliance> /api/

How to play

In order to work with REST APIs, there are various REST API client tools  :

 

 

  • Internet Browser : Put a REST API call into the browser Address Bar

 

  • CURL :  Command line tool for HTTP client

 

curl -k -u username:password -X GET "Accept: application/json" https://<IP or hostname of appliance>/api/

 


  • Insomnia : A powerful REST API client with cookie management, code generation, authentication for Linux, Mac and Window etc.

 

HTTP Methods

Red Hat CloudForms API uses JSON (Javascript Object Notation Format) for data exchange format.  JSON is a commonly used format for data exchange and storing. The primary or most commonly used HTTP verbs are POST, GET, PUT, PATCH, OPTIONS, HEAD and DELETE. These correspond to create, read, update, delete (or CRUD) operations respectively.

 

Method DEFINITION Example (Using CURL)
GET Return a specific resource curl -k -u user:password -X GET “Accept: application/json”

https://<IP>/api/providers/

POST Perform an action on the resource curl -k –user user:password -i -X POST -H “Accept: application/json” -d ‘ { “type” : “ManageIQ::Providers::Redhat::InfraManager”, “name” : “RHEVM Provider”, “hostname” : “hostname of provider”, “ipaddress” : “IP”, “credentials” : { “userid” : “username”, “password” : “*****”}}’

https://<IP>/api/providers

PUT Update or replace  a resource curl -k –user username:password -i -X PUT -H “Accept: application/json”
-d ‘{ “name” : “updated service name” }’
   http://<IP>/api/services/<service_id>
DELETE Delete a resource curl -k –user user:password -i -X DELETE -H “Accept: application/json”

https://<IP>/api/providers/<provider_id&gt;

OPTIONS Get the metadata curl -k –user username:password -X OPTIONS “Accept: application/json”

https://<IP>/api/providers/

HEAD Same as GET, but transfers the status line and header section only. HEAD method is identical to GET except that the server MUST NOT return a message body in response.This method is often used for testing hypertext links for validity, accessibility, and recent modification.
PATCH Update or modify a resource curl -k –user username:password -i -X PATCH -H “Accept: application/json”
-d ‘[{ “action”: “edit”, “path”: “name”, “value”: “A new Service name” },{ “action”: “add”, “path”: “description”, “value”: “A Description for the new Service” },
 { “action”: “remove”, “path”: “display” }
]’
   http://<IP>/api/services/<service_id>

 

Updating resources

As shown in the above table, there are a couple of ways to update attributes in a resource. You can update a resource with PUT or PATCH method. Now, the question is When to use PUT and When PATCH?

 

For Example

“When a client needs to replace an existing Resource entirely, they can use PUT. When they’re doing a partial update, they can use HTTP PATCH.”

For instance, when updating a single field of the Resource, sending the complete Resource representation might be cumbersome and utilizes a lot of unnecessary bandwidth. In such cases, the semantics of PATCH make a lot more sense.

 

How to authenticate REST APIs

REST APIs authentication can be done by two ways :

 

  • Basic Authentication : The most simple way to deal with authentication is to use HTTP basic authentication in which the username and password credentials are passed with each HTTP request.

  • Token Based Authentication: For multiple API calls to the appliance, it is recommended to use this approach. In this approach, client requests a token for the username and password. Then the token is used instead of username and password for each API call.

 

Acquiring a Token :

Request:

 curl -k -u user:password -X GET "Accept: application/json" https://<IP>/api/auth

Response:

{"auth_token":"4cb1fb32508350796caf32c12808fee2","token_ttl":600,"expires_on":"2017-12-01T11:25:06Z"}

 

Query with Token

curl -k -i -X GET "Accept: application/json" -H “X-Auth-Token: “token” https://<IP>/api/hosts


Delete a Token

curl -k -i -X DELETE -H "Accept: application/json" -H "X-Auth-Token: 21fe54dd14dc89c219d62f651497a54" https://<IP>/api/auth


Moreover, the duration of token is about 10 minutes and we can change/modify the duration from CloudForms operational portal by navigating to
Configuration -> Server -> Advanced -> api: -> token_ttl

Query Specification

 

Query specification identifies the controls available when querying collections. While querying, we can specify control attributes in the GET URL as value paris. There are three main techniques comes under query specifications. Let’s take a look on them.

 

Paging : In this capability, there are two attributes available as offset and limit. Offset means first item to return and limit means the number of items to return.

Sorting: In sorting, we can sort the attributes by order , options and attributes. For example: by specifying “sort_by=atr1,atr2” , “sort_order=asc or des”

Filtering:  This helps user to filter the data according to the use case. The syntax for filters is :

filter[]=attribute op value

where op means operators 

 

Return Codes

 

Success :  200 : OK, 201 : Created, 202 : Accepted, 204 : No content

 

Client Errors: 400 : Bad Request, 401 : Unauthorized, 403 : Forbidden, 404 : Not Found, 415 : Unsupported Media Type

 

Server Errors: 500 : Internal Server error

 

Troubleshooting

A good place to troubleshoot is to look into standard log files under /var/www/miq/vmdb/log on the CloudForms appliance. All the api related logs are recorded under /var/www/miq/vmdb/log/api.log. In order to dig deeper, changing the level of log is much recommended. You can change the log level by navigating to Configuration → Server → Advanced → :level_api: debug.

Conclusion

I hope after reading this article you will get basic understanding about how CloudForms can be managed via REST API’s. You can find the full Rest API documentation here.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s