Chapter 1. Specification

1.1. HTTP Basics

1.1.1. REST API Entry Point

The REST API is available via the /api URL prefix. It is accessed on the Red Hat CloudForms Management Engine server as follows: 

https://<cfmeHost_fqdn>/api

Response 

{
  "name" : "API",
  "description" : "REST API",
  "version" : "2.0.0",
  "versions" : [
    {
      "name" : "2.0.0",
      "href" : "https://hostname/api/v2.0.0"
    },
  ]
  "collections" : [
    {
      "name" : "automation_requests",
      "href" : "https://hostname/api/automation_requests",
      "description" : "Automation Requests"
    },
    {
      "name" : "availability_zones",
      "href" : "https://hostname/api/availability_zones",
      "description" : "Availability Zones"
    },
    ...
  ]
}
  • version is the current API version, accessible via either of the following:
  • /api/
  • /api/v2.0.0/
  • versions lists all the earlier API versions that are still exposed via their respective entry points:
  • /api/vVersion/

1.1.2. Supported Content Types

Requests: 

Accept: application/json

Responses: 

Content-Type: application/json

1.1.3. URL Paths

The recommended convention for URLs is to use alternative collection or resource path segments, relative to the API entry point as described in the following example:

URLDescription

/api

The REST API Entrypoint

/api/vVersion

The REST Entrypoint for a specific version of the REST API

/api/:collection

A top-level collection

/api/:collection/:id

A specific resource of that collection

/api/:collection/:id/:subcollection

Sub-collection under the specific resource

1.1.5. Updating Resources

Use the following methods to update attributes in a resource:

  • Update a resource via the PUT HTTP Method
  • Update a resource via a POST Method with an edit action.
  • Update a resource via the PATCH HTTP Method

While PUT is the common method, the PATCH mechanism gives better control on which attribute to edit or add, and enables removal, which is not available with the other two methods.

1.1.6. Modifying Resource Attributes

PUT /api/vms/42 

{
  "name" : "A new VM name",
  "description" : "A Description for the new VM"
}

POST /api/vms/42 

{
  "action" : "edit",
  "resource" : {
    "name" : "A new VM name",
    "description" : "A Description for the new VM"
  }
}

PATCH /api/vms/42 

[
  { "action": "edit", "path": "name", "value": "A new VM name" },
  { "action": "add", "path": "description", "value": "A Description for the new VM" },
  { "action": "remove", "path": "policies/3/description" }
]

In the PATCH implementation, path either references local attributes or attributes from a related resource in a subcollection.

1.1.7. Return Codes

Success

  • 200 OK - The request has succeeded without errors, this code should be returned for example when retrieving a collection or a single resource.
  • 201 Created - The request has been fulfilled and resulted in a new resource being created. The resource is available before this status code is returned. The response includes the HTTP body of the newly created resource.
  • 202 Accepted - The request has been accepted for processing, but the processing has not been completed. Like, resource is not fully available yet. This status code is usually returned when the resource creation happens asynchronously. In this case the HTTP response includes a pointer to monitor or a job where the client can query to get the current status of the request and the estimate on when the request will be actually fulfilled.
  • 204 No Content - The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta information. This HTTP response is commonly used for the DELETE requests, as the resource that was deleted does not exists anymore.

Client Errors

  • 400 Bad Request - The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications. In REST API this status code should be returned to client when the client use the wrong combination of attributes, like expanding the non-existing collection, or using the pagination parameter incorrectly. Another use-case could be creating or performing actions on the resource, when the wrong JSON serialization of the resource or action is used.
  • 401 Unauthorized - The request requires user authentication. The response MUST include a Authenticate header field containing a challenge applicable to the requested resource. If the request include Authenticate header, then this HTTP status code might indicate that the current user is not authorized to perform given action or to access given resource.
  • 403 Forbidden - The server understood the request, but is refusing to fulfill it. Authorization will not help in this case. This HTTP status code might indicate that the action performed is not supported for this resource or collection.
  • 404 Not Found - In this case, the server has not found anything that matches with the URL.
  • 415 Unsupported Media Type - The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method. This error must be returned, when the client is explicitly asking for format other than JSON (application/json).

Server Errors

  • 500 Internal Server Error - The server encountered an unexpected condition which prevented it from fulfilling the request. This error code must be used when an exception is raised in the application and the exception has nothing to do with the client request.

1.2. CRUD Examples

The following examples show the basic CRUD operations (Create, Read, Update, Delete) using the REST API.

The commands below use basic authentication via the --user admin:smartvm credentials argument. For multiple API calls, it is recommended to access the Red Hat CloudForms Management Engine REST API via token-based authentication. See Authentication for details.

Show a Collection of Resources

Get a collection of services: GET /api/services 

curl --user admin:smartvm
	-i -X GET -H "Accept: application/json"
	https://hostname/api/services

Return a Single Resource

Return a single service: GET /api/services/:id 

curl --user admin:smartvm
	-i -X GET -H "Accept: application/json"
	https://hostname/api/services/1

Create a Resource

Create a new provider: POST /api/providers 

curl --user admin:smartvm
      -i -X POST -H "Accept: application/json"
      -d '{
            "type"      : "EmsRedhat",
            "name"      : "RHEVM Provider",
            "hostname"  : "rhevm.local.com",
            "ipaddress" : "192.168.5.1",
            "credentials" : {
              "userid"   : "admin",
              "password" : "12345"
            }
      }'
      https://hostname/api/providers

Update a Resource

Update the name of a service: PUT /api/services/:id 

curl --user admin:smartvm
      -i -X PUT -H "Accept: application/json"
      -d '{ "name" : "updated service name" }'
      https://hostname/api/services/1

Delete a Resource

Delete a service: DELETE /api/services/:id 

curl --user admin:smartvm
	-i -X DELETE -H "Accept: application/json"
	https://hostname/api/services/1

1.3. Authentication

There are two methods of authentication for the Red Hat CloudForms Management Engine REST API:

  • Basic Authentication: The user and password credentials are passed in with each HTTP request.
  • Token based Authentication: The client requests a token for the username/password credentials specified. Then the token is used in lieu of the username/password for each subsequent API call.

1.3.1. Using Basic Authentication

The following example demonstrates how to use basic authentication: 

$ curl --user username:password
	  -i -X GET -H "Accept: application/json"
	  https://hostname/api/services/1013

Red Hat recommends token-based authentication for multiple REST API calls to the CloudForms Management Engine.

1.3.2. Using Authentication Tokens

Authentication Tokens:

  • Are associated with the user credential.
  • Provide the necessary identification for RBAC in subsequent REST calls.
  • Expire after a certain amount of time (10 minutes by default).

Request

$ curl --user username:password
        -i X GET -H "Accept: application/json"
        https://hostname/api/auth

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "auth_token" : "af0245-238722-4d23db",
  "expires_on" : "2013-12-07T18:20:07Z"
}

Request using Token based authentication

$ curl -i -X GET -H "Accept: application/json"
       -H "X-Auth-Token: af0245-238722-4d23db"
       https://hostname/api/services/1013

Failed response due to invalid token

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Application"
...

When a request fails due to an invalid token, the client must re-authenticate with the user credentials to obtain a new Authentication Token.

1.4. JSON Specification

The API uses JSON throughout; the Content-Type for all requests and responses is application/json.

As is general practice with REST, clients should not make assumptions about the server’s URL space. Clients are expected to discover all URL’s by navigating the API. To keep this document readable, we still mention specific URL’s, generally in the form of an absolute path. Clients should not use these, or assume that the actual URL structure follows these examples, and instead use discovered URL’s. Any client should start its discovery with the API entry point, here denoted with /api.

1.4.1. Basic types

The following are basic data types and type combinators that are used throughout:

NameExplanationExample serialization

Integer

Integer value

{ "id" : 10 }

String

JSON string

{ "state" : "running" }

URL

Absolute URL

{ "href" : "http://SERVER/vms/1/start" }

Timestamp

Timestamp in ISO8601 format

{ "created" : "2013-12-05T08:15:30Z" }

Array[T]

Array where each entry has type T

{ "vms" : [ { "id" : 1 }, { "id" : 2 }] }

Ref[T]

A reference to a T, used to model relations, the T is a valid Resource identifier

{ "vm" : { "href" : URL } }

Collection

Array[T] where T represents a Ref[T], this might allow actions to be executed on all members as a single unit

{ "vms" : { "count" : 2, "resources" : [ { "href" : URL}, { "href" : URL } ], "actions" : [] }

Struct

A structure with sub-attributes

"power_state": {"state" : "ON", "last_boot_time" : "2013-05-29T15:28Z", "state_change_time" : "2013-05-29T15:28Z"}

1.4.2. Common Attributes and Actions

The following describes attributes and actions that are shared by all resources and collections defined in this API.

Table 1.1. Attributes

AttributeTypeDescription

id

Integer

An integer identifier for the referenced resource

href

Ref(self)

A unique self reference

name

String

A human name of the resource 

{
  "href" : "https://hostname/api/resources/1",
  "id" : 1,
  "name" : "first_resource"
}

Table 1.2. Actions

ActionHTTP methodDescription

create

POST

Create new resource in the collection

edit

PUT/PATCH/POST

Edit attributes in resource

delete

DELETE

Delete resource

Note

The availability of these common actions depends on the role and permissions that the current API user has for a particular resource.

1.4.3. Collections

Resources can be grouped into collections. Each collection is unordered, and is homogeneous so that it contains only one type of resource. Resources can also exist outside any collection; these resources are referred to as singleton resources. Collections are themselves resources as well.

Collections can exist globally, at the top level of an API, and can also be contained inside a single resource. The latter are referred to as sub-collections. Sub-collections are usually used to express a relationship where one resource is contained within another.

Collections are serialized in JSON in the following way: 

{
  "name" : "String",
  "count": String,
  "subcount": String,
  "resources": [ ... ],
  "actions": [ ... ]
}
  • The count attribute in a collection always denotes the total number of items in the collection, not the number of items returned.
  • The subcount attribute in a collection depicts the number of items returned.
  • The resources attribute is an Array[T], where T might be a list of references to the T or, if expanded, a list of resources with all attributes.
  • The actions attribute contains an Array of actions that can be performed against the collection resources.

1.4.4. Action Specification

The representation of each resource will only contain an action and its URL if the current user is presently allowed to perform that action against that resource. Actions will be contained in the actions attribute of a resource; that attribute contains an array of action definition, where each action definition has a rel, method and a href attribute.

  • name attribute contains the action name
  • method attribute states the HTTP method that must be used in a client HTTP request in order to perform the given action (eg. GET, POST, PUT, DELETE)
  • href attribute contains the absolute URL that the HTTP request should be performed against
  • form is an optional attribute that references a JSON document which describes the resource attributes that can be provided in the message body when performing this action. This description indicates which of those attributes are mandatory and which are optional.

Collection actions

The actions performed against a collection of resources, are in most cases batch operations against multiple resources. The action request must include an HTTP body with the action name and the list of resource representations that the action will be performed against.

The resource representation might include the resource attributes as they can change the way how the action is actually performed. In the example below, the first resource is started with enable_ipmi attribute, but the second resource omits this attribute which means the default value will be used.

Sample JSON request body for collection action:

POST /api/vms 

{
  "action": "start",
  "resources" : [
    { "href" : "https://hostname/api/vms/1", "enable_ipmi" : "enabled", "initial_state" : "started" },
    { "href" : "https://hostname/api/vms/2" }
  ]
}

Actions in collection: 

{
  "name" : "String",
  "count": String,
  "subcount": String,
  "resources": [ ... ],
  "actions": [
    {
	"name"   : "shutdown",
	"method" : "post",
	"href"   : "URL"
    },
    {
	"name"   : "restart",
	"method" : "post",
	"href"   : "URL"
    },
    {
	"name"   : "poweron",
	"method" : "post",
	"href"   : "URL"
    },
    {
	"name"   : "poweroff",
	"method" : "post",
	"href"   : "URL"
    },
    {
	"name"   : "suspend",
	"method" : "post",
	"href"   : "URL"
    },
    {
	"name"    : "edit",
	"method" : "post",
	"form"   : { "href" : "https://hostname/api/vms?form_for=add" },
	"href"   : "URL"
    },
    {
	"name"   : "destroy",
	"method" : "delete",
	"href"   : "URL"
    }
  ]
}

Resource actions

An action performed against a given resource is always described in the body of the HTTP request. The HTTP body could contain a list of resource attributes that dictate how the state of the receiving resource is to be changed once the action is performed. At minimum the JSON document in the message body must contain the name of the action to be performed.

In cases where no attributes are required to perform an action the HTTP body will contain an empty JSON document, in which case default values will be assigned to the corresponding attributes.

Sample JSON request body for resource action:

POST /api/vms/123 

{
  "action"   : "start",
  "resource" : { "enable_ipmi" : "enabled" }
}

POST /api/vms/321 

{
  "action"   : "start",
  "resource" : {}
}

Actions in a resource: 

{
  "href"  : "Ref(self)",
  "id"    : Integer,
  "name"  : "resource human name",
  "actions" : [
    {
	"name"   : "edit",
	"method" : "post",
	"form"   : { "href" : "https://hostname/api/vms?form_for=edit" },
	"href"   : "URL"
    }
  ]
}

1.4.5. Forms

Getting a Form

The URL to fetch a form is part of the action serialization. In a case when no form is referenced, the action does not require any attributes to be performed.

Resource including an action with a Form: 

{
  "href" : "Ref(self)",
  "id" : Integer,
  "name" : "resource human name",
  "actions": [
    {
	"name    : "edit",
	"method" : "post",
	"form"   : { "href" : "https://hostname/vms?form_for=edit" },
	"href"   : "URL"
    }
  ]
}
GET /api/vms?form_for=edit HTTP/1.1

Example of a Form: 

{
  "required" : [ "name", "host" ],
  "optional" : [ "description" ]
  "internal" : [ "power_state", "created_on"]
}

The following describes the semantics of the attribute identifiers:

  • required - These attributes must be specified for the action to be carried out.
  • optional - These are optional attributes, which may be specified and processed by the action. These may be shown in a UI but not enforced.
  • internal - It is not necessary to define these, but they are required for a UI form to show and extended a form with more attributes than the required and optional identifiers permit. This identifier shows what attributes are system managed and not modifiable by the REST client.

1.5. Query Specification

This specification identifies the controls available when querying collections.

1.5.1. Control Attributes

The controls are specified in the GET URL as attribute value pairs as follows: 

GET /api/resources?ctl1=val1&ctl2=val2
CategoryAttributeSemantics

Paging

  
 

offset

0-based offset of first item to return

 

limit

number of items to return. If 0 is specified then the remaining items are returned

Scope

  
 

filter[]

One or more filters to search on. See Filtering below.

 

attributes=atr1,atr2,…​

Which attributes in addition to id and href to return. If not specified or all (default is attributes=all), then all attributes are returned

 

expand=resources

To expand the resources returned in the collection and not just the href. See Expanding Collection below

Sorting

  
 

sort_by=atr1,atr2,…​

By which attribute(s) to sort the result by

 

sort_order=ascending or descending

Order of the sort

  • The count attribute in a collection always denotes the total number of items in the collection, not the number of items returned.
  • The subcount attribute in a collection denotes the number of items from the collection that were returned, for example as the result of a paged request.

1.5.2. Filtering

GET requests against collections support the following query parameters to enable filtering:

  • filter[]: The SQL filter to use for querying the collection. 
GET /api/resources?filter[]=name='myservice%25'

The query above requests resources that begin with the name myservice. String values must be contained in single or double quotes. Special characters within the quotes must be URL encoded. In the example above, the database wildcard character, %, is encoded as %25.

1.5.3. Expanding Collections

While in the JSON serialization example the description says that the resource might be a list of references to the resource, using the expand parameter returns a full JSON serialization of the resource instead:

GET /api/vms 

{
  "name" : "vms"
  "count": 2,
  "subcount": 2,
  "resources": [
    { "href" : "https://hostname/api/vms/1" },
    { "href" : "https://hostname/api/vms/2" }
  ],
  "actions": []
}

GET /api/vms?expand=resources 

{
  "name" : "vms"
  "count": 2,
  "subcount": 2,
  "resources": [
    {
      "href" : "https://hostname/api/vms/1",
      "id" : 1,
      "name" : "My First VM",
      ...
    },
    {
      "href" : "https://hostname/api/vms/2",
      "id" : 2,
      "name" : "My Second VM",
      ...
    }
  ],
  "actions": []
}