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
Name | Description |
status | HTTP status text e.g. ok, not_found, etc |
data | The data requested from the API (may be null in cases where there is no data to return) |
type | The type of data e.g. application, cartridge, etc (may be null in cases where there is no data) |
messages | An Array of messages returned to the client (See API Messages) |
API version | The 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 versions | An Array of supported API versions |
API Messages
Each response from the REST API may contain 0 or more messages.
Name | Description |
severity | The severity of the message e.g. debug, info, warning, error or result |
text | The text of the message |
field | Indicates that the message is relevant to a particual field in the resource. Used for validation errors. May be null. |
exit code | Exit 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:
name | Description |
method | HTTP method to use with resource link: GET, PUT, POST or DELETE |
href | The full URI for the resource |
required parameters | An Array of input parameters that the client is required to provide |
optional parameters | An Array of optional input parameters |
Each required input parameter has the following attributes:
Name | Description |
name | The name of the parameter |
type | The type of the paramater e.g. String, Integer, Array or Boolean |
description | A brief description of the paramater |
valid options | An Array of valid values (May be empty) |
invalid options | An Array of invalid values (May be empty) |
Each optional input parameter has the following attributes:
Name | Description |
name | The name of the parameter |
type | The type of the paramater e.g. String, Integer, Array or Boolean |
description | A brief description of the paramater |
valid options | An Array of valid values (May be empty) |
default value | The 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. |