2.3. Resource 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.
The following table describes the elements contained in each resource link.
| Element Name | Description |
|---|---|
href | URL for resource link |
method | HTTP method to use with resource link: GET, PUT, POST, or DELETE |
required parameters | An array of input parameters required from the client |
optional parameters | An array of optional input parameters |
The following table describes attributes associated with each required input parameter.
| Name | Description |
|---|---|
name | Name of parameter |
type | Type of parameter, for example String, Integer, Array, or Boolean |
description | Brief description of the parameter |
valid options | An array of valid options, may be empty |
invalid options | An array of invalid options, may be empty |
The following table describes attributes associated with each optional parameter.
| Name | Description |
|---|---|
name | Name of parameter |
type | Type of parameter, for example String, Integer, Array, or Boolean |
description | Brief description of the parameter |
valid options | An array of valid options, may be empty |
Default | Default for the optional parameter if not provided by the client |
The following example shows the API representation in both XML and JSON syntax.
XML Representation
<link>
<optional-params/>
<required-params>
<param>
<type>string</type>
<valid-options/>
<name>id</name>
<description>Name of the domain</description>
</param>
</required-params>
<href>https://openshift.redhat.com/broker/rest/domains</href>
<rel>Create new domain</rel>
<method>POST</method>
</link>
JSON Representation
{
"required_params": [
{
"type": "string",
"valid_options": [],
"description": "Name of the domain",
"name": "id"
}
],
"method": "POST",
"optional_params": [],
"href": "https://openshift.redhat.com/broker/rest/domains",
"rel": "Create new domain"
}
Resource links from API responses can be hidden with the
nolinks parameter. The nolinks parameter can be included with all supported APIs and can be set to true or false. If the nolinks parameter is not included, it automatically defaults to false. If the nolinks parameter is included and set to true, the resource links are excluded from the API response resulting in a concise output and improved general processing speed.
The following examples show the REST API responses to
GET and PUT methods with and without the nolinks parameter.
$ curl -X GET https://openshift.redhat.com/broker/rest/user --user user@example.com
{
"api_version": 1.6,
"data": {
"capabilities": {
"subaccounts": true,
"gear_sizes": [
"small",
"medium"
],
"plan_upgrade_enabled": true,
"private_ssl_certificates": true,
"inherit_on_subaccounts": [
"gear_sizes"
]
},
"consumed_gears": 2,
"created_at": "2013-08-14T19:12:59Z",
"id": "520bd6bbdbd93c3dee00000d",
"links": {
"ADD_KEY": {
"href": "https://openshift.redhat.com/broker/rest/user/keys",
"method": "POST",
"optional_params": [],
"rel": "Add new SSH key",
"required_params": [
{
"description": "Name of the key",
"invalid_options": [],
"name": "name",
"type": "string",
"valid_options": []
},
{
"description": "Type of Key",
"invalid_options": [],
"name": "type",
"type": "string",
"valid_options": [
"ssh-rsa",
"ssh-dss",
"ssh-rsa-cert-v01@openssh.com",
"ssh-dss-cert-v01@openssh.com",
"ssh-rsa-cert-v00@openssh.com",
"ssh-dss-cert-v00@openssh.com"
]
},
{
"description": "The key portion of an rsa key (excluding ssh-rsa and comment)",
"invalid_options": [],
"name": "content",
"type": "string",
"valid_options": []
}
]
},
"LIST_KEYS": {
"href": "https://openshift.redhat.com/broker/rest/user/keys",
"method": "GET",
"optional_params": [],
"rel": "List SSH keys",
"required_params": []
}
},
"login": "user@example.com",
"max_gears": 10,
"plan_id": "free",
"plan_state": "ACTIVE",
"usage_account_id": null
},
"messages": [],
"status": "ok",
"type": "user",
"version": "1.6"
}
Example 2.2. API Response to GET Method with nolinks=true
$ curl -X GET https://openshift.redhat.com/broker/rest/user?nolinks=true --user user@example.com
{
"data": {
"capabilities": {
"gear_sizes": [
"small",
"medium"
],
"plan_upgrade_enabled": true,
"private_ssl_certificates": true,
"subaccounts": false,
"max_storage_per_gear": 5
},
"consumed_gears": 5,
"created_at": "2013-02-07T22:48:58Z",
"id": "51142f5adbd93ce16a0005b3",
"login": "user@example.com",
"max_gears": 16,
"plan_id": "silver",
"plan_state": "ACTIVE",
"usage_account_id": "2526383"
},
"messages": [],
"status": "ok",
"type": "user",
}
Example 2.3. API Response for PUT Method with nolinks=true
$ curl -X PUT https://openshift.redhat.com/broker/rest/user --user user@example.com --data "plan_id=free" --data "nolinks=true"
{
"data": {
"capabilities": {
"plan_upgrade_enabled": true,
"subaccounts": false,
"gear_sizes": [
"small"
]
},
"consumed_gears": 0,
"created_at": "2013-05-29T23:18:16Z",
"id": "51a68cb836905d42c3000016",
"login": "user",
"max_gears": 3,
"plan_id": "free",
"plan_state": "ACTIVE",
"usage_account_id": "2223379"
},
"errors": {},
"messages": [],
"status": "ok",
"type": "account",
}
