Authentication

The OpenShift API uses Basic Authentication. A client is required to send the username and password, separated by a colon, with all requests to correctly authenticate. For example, send the credentials as username:password. This string is encoded with Base64 algorithm, and transmitted in the HTTP authorization header in the formats shown below.

Using Ruby

  require 'base64'
  base64string = Base64.encode64("#{username}:#{password}").strip
  headers = { "Authorization" => "Basic #{base64string}" }

Using Python

  import base64
  base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
  request.add_header("Authorization", "Basic %s" % base64string)

Using cURL

The cURL library supports basic authentication using the --user or -u option, as shown in the example below.
  $ curl -k https://openshift.redhat.com/broker/rest/user --user "user@myemail.com:password"

API Response

Each response from the REST API contains te following information
NameDescription
statusHTTP status text e.g. ok, not_found, etc
dataThe data requested from the API (may be null in cases where there is no data to return)
typeThe type of data e.g. application, cartridge, etc (may be null in cases where there is no data)
messagesAn Array of messages returned to the client (See API Messages)
API versionThe API version requested by client and returned by the API. The version defaults to latest if the client does not specify a version (See Version)
supported API versionsAn Array of supported API versions

API Messages

Each response from the REST API may contain 0 or more messages.
NameDescription
severityThe severity of the message e.g. debug, info, warning, error or result
textThe text of the message
fieldIndicates that the message is relevant to a particual field in the resource. Used for validation errors. May be null.
exit codeExit code returned from API (0 if everyhting is ok)

Note: Messages with severity=result contain information that should be passed on to the user. For example the database username and password.

API Version

Every OpenShift REST API call returns the current API version, and other versions that are supported.
For example:
{
  "supported_api_versions": [
   1.0,
   1.1,
   1.2,
   1.3,
   1.4
  ],
  "api_version": 1.5
}
To request a specific API version, the client must include a HTTP header with the request.
  JSON Clients       Accept: application/json; version=1.4
 
  XML Clients        Accept: application/xml; version=1.4
If the version requested by the client is not supported, the server responds with the HTTP status code 406, as shown below.
{
  "messages": [
    {
      "field": null,
      "severity": "error",
      "text": "Requested API version 2.0 is not supported. Supported versions are 1.0, 1.1, 1.2, 1.3, 1.4"
    }
  ],
  "status": "not_acceptable",
  "supported_api_versions": [
    1.0,
    1.1,
    1.2,
    1.3,
    1.4
  ],
  "api_version": 1.4
}

Response Type

Although OpenShift supports both XML and JSON response formats, the default server response is in JSON. To receive the response in XML, send the following HTTP header with your request:
  Accept: application/xml
Example using cURL
  $ curl -k "https://openshift.redhat.com/broker/rest/api" -H "Accept: application/xml"

Links

The OpenShift REST API implements the Hypermedia as the Engine of Application State, or HATEOAS, design principle of the REST application architecture. This principle implies that the interaction between a client and a network application happens entirely through links provided dynamically by the application server. No prior knowledge, beyond a generic understanding of REST and HTTP protocol, is required from the REST client on how to interact with any particular application or server. Entry to the REST application by a REST client is through a simple fixed URL. All future actions the client takes are discovered within resource representations returned from the server. The client selects the links within these resources to navigate to the required resource.

Each resource returned by the OpenShift REST API will have an array of relevant links embedded in it. Each link has the following attributes:
nameDescription
methodHTTP method to use with resource link: GET, PUT, POST or DELETE
hrefThe full URI for the resource
required parametersAn Array of input parameters that the client is required to provide
optional parametersAn Array of optional input parameters

Each required input parameter has the following attributes:
NameDescription
nameThe name of the parameter
typeThe type of the paramater e.g. String, Integer, Array or Boolean
descriptionA brief description of the paramater
valid optionsAn Array of valid values (May be empty)
invalid optionsAn Array of invalid values (May be empty)

Each optional input parameter has the following attributes:
NameDescription
nameThe name of the parameter
typeThe type of the paramater e.g. String, Integer, Array or Boolean
descriptionA brief description of the paramater
valid optionsAn Array of valid values (May be empty)
default valueThe value this parameter defaults to if not provided by the client

Note: The links can be excluded from the API response by passing nolinks=true to any API call.

HTTP Status Codes

The OpenShift REST API attempts to return standard HTTP status codes, with the more common status codes shown in the table below along with a brief description of each.

Code Text Description
200 OK Standard response for successful HTTP requests.
201 Created The resource was successfully created.
204 No content The requested delete operation was successful.
301 Moved Permanently The resource has moved, and all future requests should be made to the new URI.
400 Bad Request Invalid request due to bad syntax.
401 Unauthorized Authentication has failed, or was not provided.
403 Forbidden The request is understood, but server is refusing to respond.
404 Not Found The requested resource cannot be found.
406 Not Acceptable The content from the requested resource is not acceptable according to the Accept headers. Possibly due to version requested, or it no longer being supported.
409 Conflict The request could not be processed because of conflict in the request.
410 Gone The resource is no longer available, and will not be available again.
422 Unprocessable Entity The request was well formed, but was not followed due to semantic errors.
500 Internal Server Error A generic error message when something is broken.
502 Bad Gateway Server was acting as a gateway or proxy, and received an invalid response.
503 Service Unavailable The server is currently unavailable; possibly down for maintenance.
504 Gateway Timeout The server was acting as a gateway or proxy and did not receive a timely response.