-
Language:
English
-
Language:
English
REST API Guide
Reference documentation for OpenShift Enterprise Representational State Transfer Application Programming Interface (REST API)
Red Hat OpenShift Documentation Team
Abstract
Chapter 1. Introduction to OpenShift Enterprise
1.1. Introduction to OpenShift API
Note
1.2. Introduction to Representational State Transfer (REST)
GET
, POST
, PUT
, and DELETE
.
Chapter 2. General API Information
2.1. Authentication
With Basic Authentication a client is required to send the user name and password, separated by a colon, with all requests to correctly authenticate. This string is encoded with Base64 algorithm and transmitted in the HTTP authorization header in the following formats.
- Ruby
require 'base64' base64string = Base64.encode64("#{username}:#{password}").strip headers = { "Authorization" => "Basic #{base64string}" }
- Python
import base64 base64string = base64.encodestring('%s:%s' % (username, password))[:-1] request.add_header("Authorization", "Basic %s" % base64string)
- cURL
- The cURL library supports basic authentication using the
--user
option, as shown in the following example.$
curl https://openshift.redhat.com/broker/rest/user --user user@example.com
You can also use authorization tokens to authenticate with the remote server instead of your user name and password. However, before you can use an authorization token you must first create one with the appropriate scope option. See Chapter 6, Authorizations for more information on creating and managing authorization tokens.
$ curl https://openshift.redhat.com/broker/rest/user -H "Authorization: Bearer token_id"
Example 2.1. cURL Command with Authorization Token
curl -X DELETE https://openshift.redhat.com/broker/rest/application/5406971c5973ca2a7f0000c6 -H "Authorization: Bearer 14fc97947174a911c3d1154aa846197cbc18ad550d7ad1cdd58aab105e65783a"
2.2. Version
cURL
command to return the API version.
$ curl "https://openshift.redhat.com/broker/rest/api"
<response> <status>ok</status> <version>1.6</version> <supported-api-versions> <supported-api-version>1.0</supported-api-version> <supported-api-version>1.1</supported-api-version> <supported-api-version>1.2</supported-api-version> <supported-api-version>1.3</supported-api-version> <supported-api-version>1.4</supported-api-version> <supported-api-version>1.5</supported-api-version> <supported-api-version>1.6</supported-api-version> </supported-api-versions> </response>
{ "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4 1.5 1.6 ], "version": "1.6" }
Accept: application/xml; version=1.5
Accept: application/json; version=1.5
<response> <messages> <message> <text>Requested API version 2.0 is not supported. Supported versions are 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6</text> <severity>error</severity> </message> </messages> <version>1.6</version> <supported-api-versions> <supported-api-version>1.0</supported-api-version> <supported-api-version>1.1</supported-api-version> <supported-api-version>1.2</supported-api-version> <supported-api-version>1.3</supported-api-version> <supported-api-version>1.4</supported-api-version> <supported-api-version>1.5</supported-api-version> <supported-api-version>1.6</supported-api-version> </supported-api-versions> <status>not_acceptable</status> </response>
{ "data": null, "messages": [ { "exit_code": null, "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, 1.5, 1.6" } ], "status": "not_acceptable", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
2.3. Resource Links
Table 2.1. Resource Elements
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 |
Table 2.2. Required Parameter Attributes
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 |
Table 2.3. Optional Parameter Attributes
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 |
<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>
{ "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" }
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.
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",
}
2.4. Response Information
Table 2.4. API Response Parameters
Name | Description |
---|---|
status | HTTP status text. Examples include ok or not_found |
data | The data requested from the API. This is null in cases where there is no data to return |
type | Type of data. For example, application or cartridge. This is null in cases where there is no data to return |
messages | An array of messages returned to the client. See Section 2.5, “Messages” for more information on API messages |
API version | API version requested by the client and returned by the API. Defaults to latest if the version is not specified. See Section 2.2, “Version” for more information |
supported API versions | An array of supported API versions |
2.5. Messages
Table 2.5. API Message Parameters
Name | Description |
---|---|
severity | Message severity. Examples include debug, info, warning, error, and result |
text | Text of the message |
field | Indicates the message is relevant to a particular field in the resource. Used for validation errors and can be null |
exit code | Exit code returned by the API. 0 if there are no issues |
Note
severity
=result contain information that is passed to the user. Examples include database user names and passwords.
2.6. Response Type
Accept: application/xml
headers = {"Accept" => "application/xml"}
request.add_header("Accept", "application/xml")
curl "https://openshift.redhat.com/broker/rest/api" -H "Accept: application/xml"
2.7. Status Codes
Table 2.6. HTTP Status Codes
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. |
Chapter 3. API Entry Point
Interaction with the OpenShift API begins with a request to the URL for the API entry point. The entry point provides navigation links to resources for a client to manage an OpenShift cloud environment.
Method | URL Structure |
---|---|
GET | /broker/rest/api |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/api
The OpenShift API resources are returned. Unnecessary information has been left out for brevity.
{ "api_version": 1.6, "data": { "API": { "href": "https://openshift.redhat.com/broker/rest/api", "method": "GET", "optional_params": [], "rel": "API entry point", "required_params": [] }, "GET_ENVIRONMENT": { "href": "https://openshift.redhat.com/broker/rest/environment", "method": "GET", "optional_params": [], "rel": "Get environment information", "required_params": [] }, "GET_USER": { "href": "https://openshift.redhat.com/broker/rest/user", "method": "GET", "optional_params": [], "rel": "Get user information", "required_params": [] }, "ADD_DOMAIN": { "href": "https://openshift.redhat.com/broker/rest/domains", "method": "POST", "optional_params": [], "rel": "Create new domain", "required_params": [ { "description": "Name of the domain", "invalid_options": [ "amentra", "aop", ........ "wise", "xnio" ], "name": "name", "type": "string", "valid_options": [] } ] }, "LIST_DOMAINS": { "href": "https://openshift.redhat.com/broker/rest/domains", "method": "GET", "optional_params": [], "rel": "List all domains you have access to", "required_params": [] }, "LIST_DOMAINS_BY_OWNER": { "href": "https://openshift.redhat.com/broker/rest/domains", "method": "GET", "optional_params": [], "rel": "List domains", "required_params": [ { "description": "Return only the domains owned by the specified user id or identity. Use @self to refer to the current user.", "invalid_options": [], "name": "owner", "type": "string", "valid_options": [ "@self", "*" ] } ] }, "SHOW_DOMAIN": { "href": "https://openshift.redhat.com/broker/rest/domain/:name", "method": "GET", "optional_params": [], "rel": "Retrieve a domain by its name", "required_params": [ { "description": "Unique name of the domain", "invalid_options": [], "name": ":name", "type": "string", "valid_options": [] } ] }, "SHOW_APPLICATION_BY_DOMAIN": { "href": "https://openshift.redhat.com/broker/rest/domain/:domain_name/application/:name", "method": "GET", "optional_params": [], "rel": "Retrieve an application by its name and domain", "required_params": [ { "description": "Unique name of the domain", "invalid_options": [], "name": ":domain_name", "type": "string", "valid_options": [] }, { "description": "Name of the application", "invalid_options": [], "name": ":name", "type": "string", "valid_options": [] } ] }, "LIST_CARTRIDGES": { "href": "https://openshift.redhat.com/broker/rest/cartridge", "method": "GET", "optional_params": [], "rel": "List cartridges", "required_params": [] }, "LIST_APPLICATIONS": { "href": "https://openshift.redhat.com/broker/rest/applications", "method": "GET", "optional_params": [], "rel": "List application", "required_params": [] }, "SHOW_APPLICATION": { "href": "https://openshift.redhat.com/broker/rest/application/:id", "method": "GET", "optional_params": [], "rel": "List application", "required_params": [ { "description": "Unique identifier of the application", "invalid_options": [], "name": ":id", "type": "string", "valid_options": [] } ] }, "LIST_AUTHORIZATIONS": { "href": "https://openshift.redhat.com/broker/rest/user/authorizations", "method": "GET", "optional_params": [], "rel": "List authorizations", "required_params": [] }, "SHOW_AUTHORIZATION": { "href": "https://openshift.redhat.com/broker/rest/user/authorization/:id", "method": "GET", "optional_params": [], "rel": "Retrieve authorization :id", "required_params": [ { "description": "Unique identifier of the authorization", "invalid_options": [], "name": ":id", "type": "string", "valid_options": [] } ] }, "ADD_AUTHORIZATION": { "href": "https://openshift.redhat.com/broker/rest/user/authorizations", "method": "POST", "optional_params": [ { "default_value": "userinfo", "description": "Select one or more scopes that this authorization will grant access to:\n\n* session\n Grants a client the authority to perform all API actions against your account. Valid for 1 day.\n* read\n Allows the client to access resources you own without making changes. Does not allow access to view authorization tokens. Valid for about 1 month.\n* userinfo\n Allows a client to view your login name, unique id, and your user capabilities. Valid for about 1 month.\n* domain/:id/view\n Grant read-only access to a single domain. Valid for about 1 month.\n* domain/:id/edit\n Grant edit access to a single domain and all its applications. Valid for about 1 month.\n* domain/:id/admin\n Grant full administrative access to a single domain and all its applications. Valid for about 1 month.\n* application/:id/view\n Grant read-only access to a single application. Valid for about 1 month.\n* application/:id/edit\n Grant edit access to a single application. Valid for about 1 month.\n* application/:id/admin\n Grant full administrative access to a single application. Valid for about 1 month.", "name": "scope", "type": "string", "valid_options": [ "session", "read", "userinfo", "domain/:id/view", "domain/:id/edit", "domain/:id/admin", "application/:id/view", "application/:id/edit", "application/:id/admin" ] }, { "default_value": null, "description": "A description to remind you what this authorization is for.", "name": "note", "type": "string", "valid_options": [] }, { "default_value": -1, "description": "The number of seconds before this authorization expires. Out of range values will be set to the maximum allowed time.", "name": "expires_in", "type": "integer", "valid_options": [] }, { "default_value": false, "description": "Attempt to locate and reuse an authorization that matches the scope and note and has not yet expired.", "name": "reuse", "type": "boolean", "valid_options": [ true, false ] } ], "rel": "Add new authorization", "required_params": [] }, "LIST_QUICKSTARTS": { "href": "https://www.openshift.com/api/v1/quickstarts/promoted.json", "method": "GET", "optional_params": [], "rel": "List quickstarts", "required_params": [] }, "SHOW_QUICKSTART": { "href": "https://www.openshift.com/api/v1/quickstarts/:id", "method": "GET", "optional_params": [], "rel": "Retrieve quickstart with :id", "required_params": [ { "description": "Unique identifier of the quickstart", "invalid_options": [], "name": ":id", "type": "string", "valid_options": [] } ] }, "SEARCH_QUICKSTARTS": { "href": "https://www.openshift.com/api/v1/quickstarts.json", "method": "GET", "optional_params": [], "rel": "Search quickstarts", "required_params": [ { "description": "The search term to use for the quickstart", "invalid_options": [], "name": "search", "type": "string", "valid_options": [] } ] } }, "messages": [], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "links", "version": "1.6" }
Chapter 4. User Information
Name | Description |
---|---|
capabilities | Map of user capabilities. See the following table for user capabilities. |
consumed_gears | Total number of gears consumed by all applications owned by user. |
login | Account user name. |
max_gears | Maximum number of gears available to the specified user. |
max_teams | Maximum number of teams a user can create. |
plan_id | Subscription plan of the specified user. |
plan_state | State of the account for the specified user. |
Name | Description |
---|---|
plan_upgrade_enabled | Indicates whether the user is on an upgraded plan. |
subaccounts | Indicates whether the user has the ability to create subaccounts. |
gear_sizes | Available gear sizes depending on the type of plan. |
max_storage_per_gear | Maximum storage in gigabytes available per gear to the specified user. |
private_ssl_certificates | Subscription plan of the specified user. |
4.1. View User Information
Provides resource links to view user information, and manage user SSH keys.
Method | Resource URL |
---|---|
GET | /broker/rest/user |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/user --user user@example.com:password
The API returns the user information resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 4, User Information for more information on all user information parameters.
{ "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", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "user", "version": "1.6" }
4.2. Parent and Child Accounts
4.2.1. Delete Child Account
Delete the specified child user account, if one exists.
Note
Method | Resource URL |
---|---|
DELETE | /broker/rest/user |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/user -d --user child_user:password
No content is returned from a successful DELETE
operation.
Chapter 5. SSH Keys
Name | Description |
---|---|
name | Name of the SSH key as specific by the user. |
content | Content of the public SSH key. |
type | Type of SSH key; for example, RSA or DSA. . |
5.1. Add SSH Key
Add an SSH key to the specified user account.
Method | Resource URL |
---|---|
POST | /broker/rest/user/keys |
Name | Description | Required | Default |
---|---|---|---|
name | Name of key | Yes | |
type | Type of SSH key | Yes | |
content | The key portion (excluding ssh-rsa and comment) | Yes |
{ "name": "mysshkey", "type": "ssh-rsa", "content": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDBJHobjmzxy8cv9A1xw9X5TlnQd0bW/19FwOC0c6jPNu9ZbtWQcAE0xfODl7ZqVPPU2qAFOh4rbL3gL2UzTyA+NwERyDrH7tMXAoXPT2L6sqExl0xxuEvb/lXUfLquMq+BMOFxxqCEg8X7GavHN72FMUHwweNybE7C82So+OFSWqFoctiWMNdNsKW4lvBd/jkIudGdRdK+/PzV75TW1LcpfsBrFOJZbd5WzDJEPNdMqOH68YDExD82VtzeJm0HEavhMY9HtxIDEmjIhtfedzCGZLe+6OxReuatw6M+n1sFxT9liprZ6NIANvbnYZKGT50hYfnIi/hZOTCvqYNS97O3" }
$ curl -X POST https://openshift.redhat.com/broker/rest/user/keys --user user@example.com:password --data-urlencode name=mysshkey --data-urlencode type=ssh-rsa --data-urlencode content=AAAAB3NzaC1yc2EhyuiBIwAAAQEA14PDPWsaZMDspZNK7ABsppzwy++Ih2tRwjBkxzC2KEcQi7v8IcyODb7qLJ72tgx3G90zRm7vQ6wuyy7rkYLIvTYiDnchy68ikjyt7wuBuSCgFcHLUdon7xn7VrskjhMN4pae6bjaY1+o4Knpfm3N72+9q/6+T52QIWCE1+Ku6UYYuOGy8qWynddw24bp4jGEKAXqTXcALuBoukC3uB+hrxvZYH1fbek6aEAQPYzO6sGqJqV1UoF0ascelhtyui8kadrKPr/5uJsPS+kGZguU16ykQb2k9K03JMSfvPP4rLe50Q9G4dSZFbUOQXdC3n13CqvsEVzizUGl0HyT8MhRqw==
The API returns the key resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 5, SSH Keys for more information on all SSH key parameters.
{ "api_version": 1.6, "data": { "content": "AAAAB3NzaC1yc2EhyuiBIwAAAQEA14PDPWsaZMDspZNK7ABsppzwy++Ih2tRwjBkxzC2KEcQi7v8IcyODb7qLJ72tgx3G90zRm7vQ6wuyy7rkYLIvTYiDnchy68ikjyt7wuBuSCgFcHLUdon7xn7VrskjhMN4pae6bjaY1+o4Knpfm3N72+9q/6+T52QIWCE1+Ku6UYYuOGy8qWynddw24bp4jGEKAXqTXcALuBoukC3uB+hrxvZYH1fbek6aEAQPYzO6sGqJqV1UoF0ascelhtyui8kadrKPr/5uJsPS+kGZguU16ykQb2k9K03JMSfvPP4rLe50Q9G4dSZFbUOQXdC3n13CqvsEVzizUGl0HyT8MhRqw", "name": "mysshkey", "type": "ssh-rsa" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Created SSH key mysshkey" } ], "status": "created", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "key", "version": "1.6" }
5.2. List User SSH Keys
Get a list of SSH keys for an OpenShift user.
Method | Resource URL |
---|---|
GET | /broker/rest/user/keys |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/user/keys --user user@example.com:password
The API returns the key resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 5, SSH Keys for more information on all SSH key parameters.
{ "api_version": 1.6, "data": [ { "content": "AAAAB3NzaC1yc2gyiketIwAAAQEA3DyqVJYGQRvbyc9TZAumxU3C5v2cBF5YCJMRobDpXWAdG6Ls4pWpk/10CwiJDQcWa8Oeq3HajnAJfalz8rGXXHp9UA9YNp4vrzYDgLkCzS5jHJzMIu7aIJS6WrFB1i1nZwnIyfthyBmSX8C8bWK3+FeZYqwmXy++t4uoZIYJ5RTffW8/1w3sgt47juikR6qzzSDh1Bks+GW5i1FxQD7PeuIZFJlAJyJLtiAPfbazX3YrroiPRL9YnB/QTpLg2jGeTtlC2UPhofbwMqAqaVpjCShHTZRW+aPGGB95BuwZMzOR2huioplkVRE7uhLsn3kFrsUBtu0SzPSSZ5fUQjeMUQ==", "name": "default", "type": "ssh-rsa" } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Found 1 ssh keys" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "keys", "version": "1.6" }
5.3. Get SSH Key Information
View the contents of an SSH key.
Method | Resource URL |
---|---|
GET | /broker/rest/user/keys/:name |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/user/keys/mysshkey --user user@example.com:password
The API returns the key resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 5, SSH Keys for more information on all SSH key parameters.
{ "api_version": 1.6, "data": { "content": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDBJHobjmzxy8cv9A1xw9X5TlnQd0bW/19FwOC0c6jPNu9ZbtWQcAE0xfODl7ZqVPPU2qAFOh4rbL3gL2UzTyA+NwERyDrH7tMXAoXPT2L6sqExl0xxuEvb/lXUfLquMq+BMOFxxqCEg8X7GavHN72FMUHwweNybE7C82So+OFSWqFoctiWMNdNsKW4lvBd/jkIudGdRdK+/PzV75TW1LcpfsBrFOJZbd5WzDJEPNdMqOH68YDExD82VtzeJm0HEavhMY9HtxIDEmjIhtfedzCGZLe+6OxReuatw6M+n1sFxT9liprZ6NIANvbnYZKGT50hYfnIi/hZOTCvqYNS97O3", "name": "mysshkey", "type": "ssh-rsa" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Found SSH key 'mysshkey'" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "key", "version": "1.6" }
5.4. Update SSH Key
Update the contents of an existing SSH key.
Method | Resource URL |
---|---|
PUT | /broker/rest/user/keys/:name |
Name | Description | Required | Default |
---|---|---|---|
type | Type of key | Yes | |
content | The key portion of an rsa key (excluding ssh-rsa and comment) | Yes |
{ "type": "ssh-rsa", "content": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDBJHobjmzxy8cv9A1xw9X5TlnQd0bW/19FwOC0c6jPNu9ZbtWQcAE0xfODl7ZqVPPU2qAFOh4rbL3gL2UzTyA+NwERyDrH7tMXAoXPT2L6sqExl0xxuEvb/lXUfLquMq+BMOFxxqCEg8X7GavHN72FMUHwweNybE7C82So+OFSWqFoctiWMNdNsKW4lvBd/jkIudGdRdK+/PzV75TW1LcpfsBrFOJZbd5WzDJEPNdMqOH68YDExD82VtzeJm0HEavhMY9HtxIDEmjIhtfedzCGZLe+6OxReuatw6M+n1sFxT9liprZ6NIANvbnYZKGT50hYfnIi/hZOTCvqYNS97O3" }
$ curl -X PUT https://openshift.redhat.com/broker/rest/user/keys/mysshkey --user user@example.com:password --data-urlencode type=ssh-rsa --data-urlencode content=AAAAB3NzaC1yc2EAAAADAQABAAABAQDBJHobjmzxy8cv9A1xw9X5TlnQd0bW/19FwOC0c6jPNu9ZbtWQcAE0xfODl7ZqVPPU2qAFOh4rbL3gL2UzTyA+NwERyDrH7tMXAoXPT2L6sqExl0xxuEvb/lXUfLquMq+BMOFxxqCEg8X7GavHN72FMUHwweNybE7C82So+OFSWqFoctiWMNdNsKW4lvBd/jkIudGdRdK+/PzV75TW1LcpfsBrFOJZbd5WzDJEPNdMqOH68YDExD82VtzeJm0HEavhMY9HtxIDEmjIhtfedzCGZLe+6OxReuatw6M+n1sFxT9liprZ6NIANvbnYZKGT50hYfnIi/hZOTCvqYNS97O3
Note
The API returns the key resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 5, SSH Keys for more information on all SSH key parameters.
{ "api_version": 1.6, "data": { "content": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDBJHobjmzxy8cv9A1xw9X5TlnQd0bW/19FwOC0c6jPNu9ZbtWQcAE0xfODl7ZqVPPU2qAFOh4rbL3gL2UzTyA+NwERyDrH7tMXAoXPT2L6sqExl0xxuEvb/lXUfLquMq+BMOFxxqCEg8X7GavHN72FMUHwweNybE7C82So+OFSWqFoctiWMNdNsKW4lvBd/jkIudGdRdK+/PzV75TW1LcpfsBrFOJZbd5WzDJEPNdMqOH68YDExD82VtzeJm0HEavhMY9HtxIDEmjIhtfedzCGZLe+6OxReuatw6M+n1sFxT9liprZ6NIANvbnYZKGT50hYfnIi/hZOTCvqYNS97O3", "name": "mysshkey", "type": "ssh-rsa" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Updates SSH key mysshkey for user@example.com" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "key", "version": "1.6" }
5.5. Delete SSH Key
Delete an SSH key from a user account.
Method | Resource URL |
---|---|
DELETE | /broker/rest/user/keys/:name |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/user/keys/mysshkey --user user@example.com:password
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Deleted SSH key mysshkey" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 118, "field": null, "severity": "error", "text": "User ssh key 'fakekey' not found." } ], "status": "not_found", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
Chapter 6. Authorizations
Name | Description |
---|---|
id | Unique OpenShift login that created this authorization token. |
scope | Scope of the authorization token to determine type of access. Scopes that are supported by a server are described in the ADD_AUTHORIZATION resource link and may be different for each server. |
note | A reminder description of what the authorization is for. |
expires_in | Total time in seconds before this authorization expires. Out of range values will be set to the maximum allowed time. |
expires_in_seconds | Remaining time in seconds before this authorization expires. |
reuse | Attempt to locate and reuse an authorization that matches the scope and note and has not yet expired. |
token | Authorization string that contains user credentials. |
scope
options that determine the type of access a user is granted with an authorization.
Name | Description |
---|---|
session | Grants a client the authority to perform all API actions against an account. Valid for one day. |
read | Access to the API is read-only, while authorization endpoints cannot be read. |
userinfo | Only read access to the /user API resource is provided. |
6.1. Add an Authorization
Add an authorization to the specified user account.
Method | URL Structure |
---|---|
POST | /broker/rest/user/authorizations |
Name | Description | Required | Default |
---|---|---|---|
scope | Scope of the authorization | No | userinfo |
note | Reminder description of authorization | No | |
expires_in | Number of seconds before authorization expires | No | -1 [a] |
reuse | Attempt to locate and reuse an authorization matching scope and note and has not expired | No | false |
[a]
For invalid values, the default is determined by the server.
|
{ "scope": "userinfo", "note": "This is my UPDATED note to myself", "expires_in": -1, "reuse": false }
$ curl -X POST https://openshift.redhat.com/broker/rest/user/authorizations --user user@example.com:password --data-urlencode scope=userinfo --data-urlencode note=This is my UPDATED note to myself --data-urlencode expires_in=-1 --data-urlencode reuse=false
The related resource links returned by the API have been left out for brevity. See Chapter 6, Authorizations for more information on all authorization parameters.
{ "api_version": 1.6, "data": { "created_at": "2013-08-21T02:02:10Z", "expires_in": 2592000, "expires_in_seconds": 2592000, "id": "52141fa2e499b2229e00009b", "identity": "user@example.com", "note": "This is my UPDATED note to myself", "scopes": "userinfo", "token": "6c85ff7f619a964e260ee6def3fc5829128dbba3f8bc11a5d89178e0d6e7a163" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Create authorization" } ], "status": "created", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "authorization", "version": "1.6" }
6.2. List Authorizations
List all authorizations for the specified user account and provide the client with additional resource links to manage existing authorizations.
Method | URL Structure |
---|---|
GET | /broker/rest/user/authorizations |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/user/authorizations --user user@example.com:password"
The API returns the authorizations resource with related resource links which have been left out for brevity. No resource links are returned if the user account does not contain any authorizations. See Chapter 6, Authorizations for more information on all authorization parameters.
{ "api_version": 1.6, "data": [ { "created_at": "2013-08-22T02:30:47Z", "expires_in": 86400, "expires_in_seconds": 6870, "id": "521577d703ef64a3120000de", "identity": "user@example.com", "note": "OpenShift Console (from 66.187.239.10 on Firefox)", "scopes": "session", "token": "187bd89d1f5172af567eb12631c45gt7415dca5c2b7jy56970b3f3a911df4697" } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "List authorizations" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "authorizations", "version": "1.6" }
6.3. Get Authorization Information
Get information about the specified authorization.
Method | URL Structure |
---|---|
GET | /broker/rest/user/authorizations/:id |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/user/authorizations/52141fa2e499b2229e00009b --user user@example.com:password
The API returns information about the specified authorization and related resource links which have been left out for brevity. See Chapter 6, Authorizations for more information on all authorization parameters.
{ "api_version": 1.6, "data": { "created_at": "2013-08-21T02:02:10Z", "expires_in": 2592000, "expires_in_seconds": 2592000, "id": "52141fa2e499b2229e00009b", "identity": "user@example.com", "note": "This is my UPDATED note to myself", "scopes": "userinfo", "token": "6c85ff7f619a964e260ee6def3fc5829128dbba3f8bc11a5d89178e0d6e7a163" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Display authorization" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "authorization", "version": "1.6" }
6.4. Update an Authorization
Update an existing authorization for the specified user account. However, currently this operation only supports updating the note
parameter of an existing authorization.
Method | URL Structure |
---|---|
PUT | /broker/rest/user/authorizations/:id |
Name | Description | Required | Default |
---|---|---|---|
note | Reminder description of authorization. | Yes |
$ curl -X PUT https://openshift.redhat.com/broker/rest/user/authorizations/52141fa2e499b2229e00009b --user user@example.com:password --data-urlencode note=This is a note to myself
The API returns the authorizations resource with related resource links which have been left out for brevity. See Chapter 6, Authorizations for more information on all authorization parameters.
{ "api_version": 1.6, "data": { "created_at": "2013-08-21T02:02:10Z", "expires_in": 2592000, "expires_in_seconds": 2592000, "id": "52141fa2e499b2229e00009b", "identity": "user@example.com", "note": "This is a note to myself", "scopes": "userinfo", "token": "6c85ff7f619a964e260ee6def3fc5829128dbba3f8bc11a5d89178e0d6e7a163" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Change authorization" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "authorization", "version": "1.6" }
6.5. Delete an Authorization
Delete the specified authorization.
Method | URL Structure |
---|---|
DELETE | /broker/rest/user/authorizations/:id |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/user/authorizations/52141fa2e499b2229e00009b --user user@example.com:password
The API returns confirmation of a successful DELETE
operation.
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Authorization 52141fa2e499b2229e00009b is revoked." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
Chapter 7. Domains
Name | Description |
---|---|
name | Name of the domain |
suffix | Domain suffix |
allowed_gear_sizes | Array of zero or more gear sizes allowed on this domain |
7.1. Create a Domain
Create a new domain for an OpenShift user account. Note that a domain is required to create applications on OpenShift Enterprise.
Method | URL Structure |
---|---|
POST | /broker/rest/domains |
Name | Description | Required | Default |
---|---|---|---|
name | Name of domain | Yes | |
allowed_gear_sizes | List of gear sizes that can be created on this domain | No |
{ "name": "mydomain", "allowed_gear_sizes": "small" }
$ curl -X POST https://openshift.redhat.com/broker/rest/domains/ --user user@example.com:password --data-urlencode name=mydomain --data-urlencode allowed_gear_sizes=small
The API returns the domain resource with related resource links which have been left out for brevity. See Chapter 7, Domains for more information on all domain parameters.
{ "api_version": 1.6, "data": { "allowed_gear_sizes": [ "small" ], "creation_time": "2013-11-07T00:28:13Z", "id": "527ade9d7f9c48d371000009", "members": [ { "explicit_role": null, "from": [ { "type": "owner", "role": "admin" } ], "id": "527ade897f9c48d371000001", "login": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "mydomain", "suffix": "rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Created domain with name mydomain" } ], "status": "created", ], "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "domain", "version": "1.6" }
7.2. List Domains
Get a list of all domains accessible to the user, regardless of ownership.
Method | URL Structure |
---|---|
GET | /broker/rest/domains |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/domains --user user@example.com:password
The API returns a list of all domains that you have access to. The related resource links returned by the API have been left out for brevity.
{ "api_version": 1.6, "data": [ { "allowed_gear_sizes": [ "small", "medium", "c9" ], "creation_time": "2013-08-20T07:21:50Z", "links": { }, "members": [ { "explicit_role": null, "from": [ { "type": "owner", "role": "admin" } ], "id": "520bd6bbdbd93c3dee00000d", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "mydomain", "suffix": "rhcloud.com" } ], "messages": [], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "domains", "version": "1.6" }
7.3. List Domains by Owner
Get a list of domains owned by a particular user, specified with the owner
parameter. If no owner is specified, it automatically defaults to self.
Method | URL Structure |
---|---|
GET | /broker/rest/domains |
Name | Description | Required | Default |
---|---|---|---|
owner | List domains owned by specified user, or @self for current user | Yes |
{ "owner": "@self" }
$ curl -X GET https://openshift.redhat.com/broker/rest/domains --user user@example.com:password --data-urlencode owner=@self
The API returns a list of domains owned by the specified user. The related resource links returned by the API have been left out for brevity.
{ "api_version": 1.6, "data": [ { "allowed_gear_sizes": [ "small", "medium", "c9" ], "creation_time": "2013-08-20T07:21:50Z", "links": { }, "members": [ { "explicit_role": null, "from": [ { "type": "owner", "role": "admin" } ], "id": "520bd6bbdbd93c3dee00000d", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "mydomain", "suffix": "rhcloud.com" } ], "messages": [], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "domains", "version": "1.6" }
7.4. Get Domain Information
Get information about an existing domain.
Method | URL Structure |
---|---|
GET | /broker/rest/domains/:name |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/domains/mydomain --user user@example.com:password
The API returns the domain resource with related resource links which have been left out for brevity. See Chapter 7, Domains for more information on all domain resource parameters.
$ curl -X GET https://openshift.redhat.com/broker/rest/domains/mydomain --user user@example.com:password
{
"api_version": 1.6,
"data": {
"allowed_gear_sizes": [
"small"
],
"creation_time": "2013-08-21T01:58:41Z",
"members": [
{
"explicit_role": null,
"from": [
{
"type": "owner",
"role": "admin"
}
],
"id": "5213a826e499b22f15000001",
"name": "user@example.com",
"owner": true,
"role": "admin",
"type": "user"
}
],
"name": "mydomain",
"suffix": "rhcloud.com"
},
"messages": [
{
"exit_code": 0,
"field": null,
"severity": "info",
"text": "Found domain mydomain"
}
],
"status": "ok",
"supported_api_versions": [
1.0,
1.1,
1.2,
1.3,
1.4,
1.5,
1.6
],
"type": "domain",
"version": "1.6"
}
7.5. Update Domain
Update an existing domain.
Method | URL Structure |
---|---|
PUT | /broker/rest/domains/:name |
Name | Description | Required | Default |
---|---|---|---|
name | Name of domain | Yes | |
allowed_gear_sizes | Array of zero or more gear sizes allowed on this domain | No |
{ "name": "mydomainX", "allowed_gear_sizes": "small" }
$ curl -X PUT https://openshift.redhat.com/broker/rest/domains/mydomain --user user@example.com --data-urlencode name=mydomainx --data-urlencode allowed_gear_sizes=small
The API returns the domain resource with related resource links which have been left out for brevity. See Chapter 7, Domains for more information on all domain parameters.
{ "api_version": 1.6, "data": { "allowed_gear_sizes": [ "small" ], "creation_time": "2013-11-07T00:28:13Z", "id": "527ade9d7f9c48d371000009", "members": [ { "explicit_role": null, "from": [ { "type": "owner", "role": "admin" } ], "id": "527ade897f9c48d371000001", "login": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "mydomainx", "suffix": "rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Changed namespace to 'mydomainx'." } ], "status": "ok", ], "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "domain", "version": "1.6" }
7.6. Remove Self from a Domain
Remove yourself from a domain.
Method | URL Structure |
---|---|
DELETE | /broker/rest/domain/:name/members/self |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/domain/mydomain/members/self --user user@example.com:password
7.7. Delete a Domain
Delete an existing domain.
Note
force
parameter to true automatically deletes all applications under that domain and then deletes the domain.
Warning
force
parameter set to true deletes all applications created within that domain. This operation cannot be reversed.
Method | URL Structure |
---|---|
DELETE | /broker/rest/domains/:name |
Name | Description | Required | Default |
---|---|---|---|
force | Force delete domain | No | false |
$ curl -X DELETE https://openshift.redhat.com/broker/rest/domains/mydomain --user user@example.com:password
If there are applications under the domain to be deleted, the API exits with an error message.
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 128, "field": null, "severity": "error", "text": "Domain contains applications. Delete applications first or set force to true." } ], "status": "unprocessable_entity", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
force
parameter to true to automatically delete the applications as part of the domain delete process.
Chapter 8. Teams
Name | Description |
---|---|
name | Name of the team |
id | Unique identifier of the team |
8.1. Create Team
Create a new team. Note that the maximum number of teams that can be created is determined by the max_teams
capability. See Chapter 4, User Information for more information on user capabilities.
- Team names must be a minimum of 2 characters in length, with a maximum length of 250 characters
- If there are multiple teams under one owner, each team must have a unique name
- Team names cannot be modified
Method | URL Structure |
---|---|
POST | /broker/rest/teams |
{ "name": "myteam", }
$ curl -X POST https://openshift.redhat.com/broker/rest/teams --user user@example.com:password --data-urlencode name=myteam
The API returns the team resource with related resource links which have been left out for brevity. See Chapter 8, Teams for more information on all team parameters.
{ "api_version": 1.6, "data": { "id": "5333d8b2a9429d1c3e0000ae", "members": [ { "explicit_role": null, "from": [ { "type": "owner", "role": "view" } ], "id": "5333d64fa9429defe8000001", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/5333d64fa9429defe8000001", "method": "GET", "optional_params": [ ], "rel": "Get member", "required_params": [ ] }, "UPDATE": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/5333d64fa9429defe8000001", "method": "PUT", "optional_params": [ ], "rel": "Update member", "required_params": [ { "description": "New role for member", "invalid_options": [ ], "name": "role", "type": "string", "valid_options": [ ] } ] }, "DELETE": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/5333d64fa9429defe8000001", "method": "DELETE", "optional_params": [ ], "rel": "Delete member", "required_params": [ ] } }, "login": "user@example.com", "owner": true, "role": "view", "type": "user" } ], "name": "myteam" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Added myteam" } ], "status": "created", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "team", "version": "1.6" }
8.2. List Teams
Get a list of teams that you are a member of.
Method | URL Structure |
---|---|
GET | /broker/rest/teams |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/teams --user user@example.com:password
The API returns a list of all teams that you are a member of. The related resource links returned by the API have been left out for brevity.
{ "api_version": 1.6, "data": [ { "id": "5333d8b2a9429d1c3e0000ae", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae", "method": "GET", "optional_params": [ ], "rel": "Get team", "required_params": [ ] }, ........ }, "name": "myteam" } ], "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Listing teams for user user@example.com" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "teams", "version": "1.6" }
8.3. List Teams by Owner
Get a list of teams owned by a particular user, specified with the owner
parameter.
Method | URL Structure |
---|---|
GET | /broker/rest/teams |
Name | Description | Required | Default |
---|---|---|---|
owner | List teams owned by specified user, or @self for current user | Yes |
{ "owner": "@self" }
$ curl -X GET https://openshift.redhat.com/broker/rest/teams --user user@example.com:password --data-urlencode owner=@self
The API returns a list of teams owned by the specified user. The related resource links returned by the API have been left out for brevity.
{ "api_version": 1.6, "data": [ { "id": "5333d8b2a9429d1c3e0000ae", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae", "method": "GET", "optional_params": [ ], "rel": "Get team", "required_params": [ ] }, ........ }, "name": "myteam" } ], "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Listing teams for user user@example.com" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "teams", "version": "1.6" }
8.4. Search Teams by Name
Search teams with the specified string.
Method | URL Structure |
---|---|
GET | /broker/rest/teams |
Name | Description | Required | Default |
---|---|---|---|
search | Search string of at least 2 characters | Yes | |
global | Boolean parameter to indicate whether global teams or teams owned by users are searched | Yes |
{ "search": "engineering", "global": true }
$ curl -X GET https://openshift.redhat.com/broker/rest/teams --user user@example.com:password --data-urlencode search=engineering --data-urlencode global=true
The API returns a list of teams matching the search string.
{ "api_version": 1.6, "data": [ { "global": true, "id": "534c7827b3868d3eb3000001", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/534c7827b3868d3eb3000001", "method": "GET", "optional_params": [ ], "rel": "Get team", "required_params": [ ] }, "LIST_MEMBERS": { "href": "https://openshift.redhat.com/broker/rest/team/534c7827b3868d3eb3000001/members", "method": "GET", "optional_params": [ ], "rel": "list members", "required_params": [ ] } }, "maps_to": "cn=engineering-team,ou=Groups,dc=example,dc=com", "name": "engineering-team" } ], "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Found 1 teams" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "teams", "version": "1.6" }
8.5. Get Team Information
Get information about an existing team.
Method | URL Structure |
---|---|
GET | /broker/rest/team/:id |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae --user user@example.com:password
The API returns the team resource with related resource links which have been left out for brevity. See Chapter 8, Teams for more information on all team resource parameters.
{ "api_version": 1.6, "data": { "id": "5333d8b2a9429d1c3e0000ae", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae", "method": "GET", "optional_params": [ ], "rel": "Get team", "required_params": [ ] }, ........ ], "name": "myteam" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Showing team 5333d8b2a9429d1c3e0000ae for user user@example.com" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "team", "version": "1.6" }
8.6. Remove Self from a Team
Remove yourself from a team owned by another user.
Method | URL Structure |
---|---|
DELETE | /broker/rest/team/:id/members/self |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/members/self --user user@example.com:password
8.7. Delete Team
Delete an existing team.
Method | URL Structure |
---|---|
DELETE | /broker/rest/team/:id |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae --user user@example.com:password
Chapter 9. Members
Name | Description |
---|---|
id | Unique identifier of member |
role | Type of role a member is provided |
type | Type of member; for example, user or team |
from | Source of the membership |
owner | Indicates whether the member is owner of the resource |
members | An array of members to add with corresponding type and role; for example, {'members': [{'login': 'foo', 'type': 'user', 'role': 'view'}, {'id': '5326534e2046fde9d3000001', 'type': 'team', 'role': 'none'}]} |
9.1. List Members of a Domain
Get a list of members that belong to the specified domain.
Method | URL Structure |
---|---|
GET | /broker/rest/domains/:name/members |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/domains/mydomain/members --user user@example.com:password
The API returns a list of all members belonging to the specified domain.
{ "api_version": 1.6, "data": [ { "explicit_role": null, "from": [ { "type": "owner", "role": "admin" } ], "id": "521bf803656c674541000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Found 1 member." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "members", "version": "1.6" }
9.2. Add or Remove Domain Members
Add or remove one or more domain members. If a member has the admin
role on a domain, they can:
- Add a team they own as a member of a domain
- Change the role of any team that is already a member of a domain
- Remove any team that is already a member of a domain
MAX_TEAMS_PER_RESOURCE
parameter.
Method | URL Structure |
---|---|
PATCH | /broker/rest/domains/:name/members |
Name | Description | Required | Default |
---|---|---|---|
role | Type of role a member has on the domain | Yes | |
id | Unique user or team identifier | No | |
login | User's login attribute; only used when the member type is 'user' | No | |
type | Indicates whether a member is a user, or a team | No | user |
members | An array of members to add with corresponding id or user login , type , and role |
{ "role": "view", "login": "member@example.com" }
$ curl -X PATCH https://openshift.redhat.com/broker/rest/domains/mydomain/members --user user@example.com:password --data-urlencode role=view --data-urlencode login=member@memberemail.com
The sample JSON response below shows that a new domain member has been added.
{ "api_version": 1.6, "data": { "explicit_role": "view", "id": "526097602587c8242100006b", "login": "member@memberemail.com", "owner": false, "role": "view", "type": "user" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Added 1 member." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "member", "version": "1.6" }
9.3. List Members of an Application
Get a list of members that belong to the specified application.
Method | URL Structure |
---|---|
GET | /broker/rest/application/:id/members |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/521bf818656c67309c000001/members --user user@example.com:password
The API returns a list of all members belonging to the specified application.
{ "api_version": 1.6, "data": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "521bf803656c674541000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Found 1 member." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "memberS", "version": "1.6" }
9.4. Add Team Member
Add a member to an existing team. Note that the maximum number of members a team can have is determined by the MAX_MEMBERS_PER_RESOURCE
configuration parameter.
Method | URL Structure |
---|---|
POST | /broker/rest/team/:id/members |
Name | Description | Required | Default |
---|---|---|---|
role | Type of role user has on the team | Yes | |
id | Unique user identifier | No | |
login | User's login attribute | No |
{ "role": "view", "login": "member@example.com" }
$ curl -X POST https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/members --user user@example.com:password --data-urlencode role=view --data-urlencode login=member@example.com
The sample JSON response below shows that a new member has been added to the specified team. Unnecessary information and related resource links returned by the API have been removed for brevity.
{ "api_version": 1.6, "data": { "explicit_role": "view", "id": "533369f861b322dfc1000003", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003", "method": "GET", "optional_params": [ ], "rel": "Get member", "required_params": [ ] }, }, "login": "member@example.com", "owner": false, "role": "view", "type": "user" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Added 1 member." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "member", "version": "1.6" }
9.5. List Members of a Team
Get a list of members that belong to the specified team.
Method | URL Structure |
---|---|
GET | /broker/rest/team/:id/members |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/members --user user@example.com:password
The API returns a list of all members belonging to the specified team.
{ "api_version": 1.6, "data": [ { "explicit_role": null, "from": [ { "type": "owner", "role": "view" } ], "id": "5333d64fa9429defe8000001", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/5333d64fa9429defe8000001", "method": "GET", "optional_params": [ ], "rel": "Get member", "required_params": [ ] }, "login": "member@example.com", "owner": false, "role": "view", "type": "user" } ], "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Found 2 members." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "members", "version": "1.6" }
9.6. Add or Remove Team Members
Add one or more members to a team, or remove them from a team.
Method | URL Structure |
---|---|
PATCH | /broker/rest/team/:id/members |
Name | Description | Required | Default |
---|---|---|---|
role | Type of role user has on the team | Yes | |
id | Unique user identifier | No | |
login | User's login attribute | No | |
members | An array of members to add with corresponding type and role | No |
{ "role": "view", "login": "member@example.com" }
$ curl -X PATCH https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/members --user user@example.com:password --data-urlencode role=view --data-urlencode login=member@example.com
The API returns the member resource with related resource links which have been left out for brevity. See Chapter 9, Members for more information on all member parameters.
{ "api_version": 1.6, "data": { "explicit_role": "view", "id": "533369f861b322dfc1000003", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003", "method": "GET", "optional_params": [ ], "rel": "Get member", "required_params": [ ] }, }, "login": "team.member@mycompany.com", "owner": false, "role": "view", "type": "user" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Updated 1 member." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "member", "version": "1.6" }
9.7. Get Member Information
Get information about an existing team member.
Method | URL Structure |
---|---|
GET | /broker/rest/team/:id/member/:id |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003 --user user@example.com:password
The API returns the member resource with related resource links which have been left out for brevity. See Chapter 9, Members for more information on all member resource parameters.
{ "api_version": 1.6, "data": { "explicit_role": "view", "id": "533369f861b322dfc1000003", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003", "method": "GET", "optional_params": [ ], "rel": "Get member", "required_params": [ ] }, }, "login": "member@example.com", "owner": false, "role": "view", "type": "user" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Showing member 533369f861b322dfc1000003" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "member", "version": "1.6" }
9.8. Update Team Member
Update the role of a team member.
Method | URL Structure |
---|---|
PUT | /broker/rest/team/:id/member/:id |
Name | Description | Required | Default |
---|---|---|---|
role | Type of role user has on the team | Yes |
{ "role": "view", }
$ curl -X PUT https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003 --user user@example.com:password --data-urlencode role=view
The API returns the member resource with related resource links which have been left out for brevity. See Chapter 9, Members for more information on all member parameters.
{ "api_version": 1.6, "data": { "explicit_role": "view", "id": "533369f861b322dfc1000003", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003", "method": "GET", "optional_params": [ ], "rel": "Get member", "required_params": [ ] }, }, "login": "member@example.com", "owner": false, "role": "view", "type": "user" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Updated member" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "member", "version": "1.6" }
9.9. Delete Team Member
Delete a team member.
Method | URL Structure |
---|---|
DELETE | /broker/rest/team/:id/member/:id |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003--user user@example.com:password
The specified member is deleted from the team, and the API returns the member resource. Other information and related resource links have been left out for brevity. See Chapter 9, Members for more information on all member parameters.
{ "api_version": 1.6, "data": { "explicit_role": "view", "id": "533369f861b322dfc1000003", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003", "method": "GET", "optional_params": [ ], "rel": "Get member", "required_params": [ ] }, }, "login": "member@example.com", "owner": false, "role": "view", "type": "user" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Updated member" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "member", "version": "1.6" }
force
parameter to true to automatically delete the applications as part of the domain delete process.
Chapter 10. Quickstarts
Name | Description |
---|---|
id | Unique identifier of the quickstart. |
search | The search term to use for the quickstart. |
10.1. List Quickstarts
List all available quickstarts. The client will only see this resource if there are quickstarts available, and it will be absent if there are none. Unlike other REST API calls, the following guidelines apply when retrieving a list of quickstarts:
- API versioning is not supported
- Only JSON is supported
- The body of the API response is different from other API responses
- Parse errors or unexpected data values must be handled by omitting the entry
Method | URL Structure |
---|---|
GET | /api/v1/quickstarts/promoted.json |
Not applicable
$ curl -X GET https://www.openshift.com/api/v1/quickstarts/promoted.json --user user@example.com
The API returns a list of all quickstarts that are available. See Chapter 10, Quickstarts for more information on all quickstart parameters.
{ "data": [ { "quickstart": { "id": "13145", "href": "https://www.openshift.com/quickstarts/drupal-7", "name": "Drupal 7", "updated": "1365011911", "summary": "An open source content management platform written in PHP powering millions of websites and applications. It is built, used, and supported by an active and diverse community of people around the world. This quickstart will download and install the most recent stable version of Drupal and then generate a new site for you. Your administrative username and password will default to admin/openshift_changeme, so don't forget to alter them once you log in!\n\nWithout sharing a filesystem, Drupal can't be web scaled, but the README.md describes a workaround that will allow you to scale if you don't need direct file upload into Drupal.\n\nCreating this quickstart may take several minutes. You may need to restart the application once the database is configured. NOTE: If you want to run the Drupal cron tasks, please install the cron cartridge.", "body": "<p>An open source content management platform written in PHP powering millions of websites and applications. It is built, used, and supported by an active and diverse community of people around the world. This quickstart will download and install the most recent stable version of Drupal and then generate a new site for you. Your administrative username and password will default to admin/openshift_changeme, so don't forget to alter them once you log in!</p>\n\n<p>Without sharing a filesystem, Drupal can't be web scaled, but the <a href=\"https://github.com/openshift/drupal-quickstart/blob/master/README.md\">README.md</a> describes a workaround that will allow you to scale if you don't need direct file upload into Drupal.</p>\n\n<p>Creating this quickstart may take several minutes. You may need to restart the application once the database is configured. NOTE: If you want to run the Drupal cron tasks, please install the cron cartridge.</p>", "cartridges": "php-*, mysql-*", "website": "http://drupal.org/", "tags": "cms, drupal, instant_app, not_scalable, php", "language": "PHP", "initial_git_url": "https://github.com/openshift/drupal-quickstart.git", "provider": "openshift" } }, ] }
10.2. Show Quickstart
Get information about the specified quickstart. The client does not have to retrieve the quickstarts list and scan for a known ID.
Method | URL Structure |
---|---|
GET | /api/v1/quickstarts/:id |
Name | Description | Required | Default |
---|---|---|---|
id | Unique identifier of the quickstart | Yes |
$ curl -X GET https://www.openshift.com/api/v1/quickstarts/12724 --user user@example.com
The API returns information about the specified quickstart.
{ "data": [ { "quickstart": { "id": "12724", "href": "https://www.openshift.com/quickstarts/wordpress-3x", "name": "WordPress 3.x", "updated": "1365011887", "summary": "A semantic personal publishing platform written in PHP with a MySQL back end, focusing on aesthetics, web standards, and usability. Currently using version 3.5.1.\n\nThe first time you access the app you'll be asked to set a username and password and give your blog a name. Be sure to track security updates from upstream.", "body": "<p>A semantic personal publishing platform written in PHP with a MySQL back end, focusing on aesthetics, web standards, and usability. Currently using version 3.5.1.</p>\n\n<p>The first time you access the app you'll be asked to set a username and password and give your blog a name. Be sure to track security updates from upstream.</p>", "cartridges": "php-*, mysql-*", "website": "http://wordpress.org", "tags": "blog, cms, instant_app, not_scalable", "language": "PHP", "initial_git_url": "git://github.com/openshift/wordpress-example.git", "provider": "openshift" } } ] }
10.3. Search Quickstarts
Search for a quickstart using a search term.
Method | URL Structure |
---|---|
GET | /api/v1/quickstarts.json?search=search_term |
Name | Description | Required | Default |
---|---|---|---|
search | Search term to use for the quickstart. | Yes |
$ curl -X GET https://www.openshift.com/api/v1/quickstarts.json?search=wordpress --user user@example.com
The API returns information about all quickstarts that match the specified search string. See Chapter 10, Quickstarts for more information on all quickstart parameters.
{ "data": [ { "quickstart": { "id": "12724", "href": "https://www.openshift.com/quickstarts/wordpress-3x", "name": "WordPress 3.x", "updated": "1365011887", "summary": "A semantic personal publishing platform written in PHP with a MySQL back end, focusing on aesthetics, web standards, and usability. Currently using version 3.5.1.\n\nThe first time you access the app you'll be asked to set a username and password and give your blog a name. Be sure to track security updates from upstream.", "body": "<p>A semantic personal publishing platform written in PHP with a MySQL back end, focusing on aesthetics, web standards, and usability. Currently using version 3.5.1.</p>\n\n<p>The first time you access the app you'll be asked to set a username and password and give your blog a name. Be sure to track security updates from upstream.</p>", "cartridges": "php-*, mysql-*", "website": "http://wordpress.org", "tags": "blog, cms, instant_app, not_scalable", "language": "PHP", "initial_git_url": "git://github.com/openshift/wordpress-example.git", "provider": "openshift" } } ] }
Chapter 11. Applications
Name | Description |
---|---|
name | Name of the application. |
framework | Application framework. For example, JBoss, PHP, or Ruby. |
domain_id | The domain ID of the application. |
embedded | List of cartridges that have been added to this application. |
creation_time | Time the application was created. |
scalable | Whether application is scaled or not scaled. The values are either true or false . |
gear_count | Number of gears for this application. |
gear_profile | Gear size of an application. For example, small . |
aliases | Application server aliases, if applicable. |
app_url | The URL to access this application. |
git_url | The URL to access the Git repository for this application. |
ssh_url | The URL to access this application using an SSH terminal. |
health_check_path | The URL to check if the application is running. |
uuid | Unique identifier for this application. |
initial_git_url | The URL that was used to initialize the Git repository for this application. |
11.1. Resolve DNS
Check whether the DNS is created with an actual DNS nameserver lookup that is not subject to caching. When DNS availability is checked with the client tools, the value gets cached for approximately 30 seconds. This REST API call checks for DNS availability by directly querying the DNS servers.
Method | URL Structure |
---|---|
GET | /broker/rest/application/:id/dns_resolvable |
Not applicable
$ curl GET https://openshift.redhat.com/broker/rest/applications/534253991015616165707776/dns_resolvable --user user@example.com
The following is an example of the API response if the DNS is resolvable. If the DNS is not resolved an error message is returned.
{ "api_version": 1.6, "data": true, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Resolved DNS myapp-mydomain.rhcloud.com" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "boolean", "version": "1.6" }
11.2. Create an Application
Create a new application. Note that if the specified domain does not exist when attempting to create an application, a domain is automatically created. See Section 7.1, “Create a Domain” for more information on how to create a domain.
Method | URL Structure |
---|---|
POST | /broker/rest/domain/:domain_name/applications |
Name | Description | Required | Default |
---|---|---|---|
name | Name of application | Yes | |
cartridges | Add cartridges to the application by specifying an array of one or more cartridges, using the name or unique ID | No | |
template | UUID of application template | No | |
scale | Mark application as scalable | No | false |
gear_size | Cartridge gear size | No | small |
initial_git_url | URL to Git source code repository that is the basis for this application | No | |
cartridges[][name] | Name of cartridge | No | |
cartridges[][gear_size] | Gear size of each individual cartridge. If gear_size is not specified, default gear size is used depending on user input | No | |
cartridges[][url] | URL to a downloadable cartridge; multiple URLs can be specified | No | |
environment_variables | Add or update application environment variables | No | |
region | Restrict the application to the specified region | No |
Note
{ "name": "myapp", "cartridges": "ruby-2.0", "scale": "true", "gear_size": "small", "initial_git_url": "" }
$ curl -X POST https://openshift.redhat.com/broker/rest/domain/mydomain/applications --user user@example.com:password --data-urlencode name=myapp --data-urlencode cartridges=ruby-2.0 --data-urlencode scale=true --data-urlencode gear_size=small
gear_size
parameter is applied to all cartridges that are added to the specified application. However, the following cURL command example shows how to apply the gear_size
parameter to individual cartridges when adding multiple cartridges to an application.
$ curl -X POST https://openshift.redhat.com/broker/rest/domain/mydomain/applications --user user@example.com:password --data-urlencode name=mysecondapp --data-urlencode cartridges=[][name]=jbosseap-6 --data-urlencode cartridges[][gear_size]=medium --data-urlencode cartridges[][name]=mysql-5.5 --data-urlencode cartridges[][gear_size]=small
The API returns information about the newly created application with related resource links which have been left out for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp was created." }, { "exit_code": 0, "field": null, "severity": "warning", "text": "HAProxy instance is started\n" } ], "status": "created", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7 ], "type": "application", "version": "1.7" }
Note
11.3. List Applications by Owner
Get a list of applications owned by a particular user, specified with the owner
parameter. If no owner is specified, it automatically defaults to self.
Method | URL Structure |
---|---|
GET | /broker/rest/applications |
Name | Description | Required | Default |
---|---|---|---|
owner | List applications owned by specified user, or @self for current user | Yes |
{ "owner": "@self" }
$ curl -X GET https://openshift.redhat.com/broker/rest/applications --user user@example.com:password --data-urlencode owner=@self
The API returns a list of applications owned by the specified user. The related resource links returned by the API have been left out for brevity.
"api_version": 1.6, "data": [ { "aliases": [ { "certificate_added_at": "2014-03-27T00:00:00Z", "has_private_ssl_certificate": true, "id": "myappalias", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/application/5333d664a9429d1c3e00000c/alias/myappalias", "method": "GET", "optional_params": [ ], "rel": "Get alias", "required_params": [ ] }, ........ }, "login": "member@example.com", "owner": false, "role": "view", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://5333d664a9429d1c3e00000c@myapp-mydomain.rhcloud.com" } ], "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Found 1 applications." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "applications", "version": "1.6" }
11.4. List Applications for a User
List all applications for the specified user.
Method | URL Structure |
---|---|
GET | /broker/rest/applications |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/applications --user user@example.com:password
The API returns a list of all applications for the specified user. The related resource links returned by the API have been left out for brevity. See Chapter 11, Applications for a description of each response parameter associated with an application.
{ "api_version": 1.6, "data": [ { "aliases": [], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-20T07:21:50Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": {}, "mysql-5.5": { "connection_url": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/", "username": "adminxcYKabL", "password": "IgsS3_wQYF38", "database_name": "myapp", "info": "Connection URL: mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } }, "framework": "php-5.4", "gear_count": 2, "gear_profile": "medium", "git_url": "ssh://5213190e2587c8817a000121@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health_check.php", "id": "5213190e2587c8817a000121", "initial_git_url": null, "links": { }, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "520bd6bbdbd93c3dee00000d", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://5213190e2587c8817a000121@myapp-mydomain.rhcloud.com" } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Found 1 applications." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "applications", "version": "1.6" }
11.5. List Applications for a Domain
List all applications for the specified domain.
Method | URL Structure |
---|---|
GET | /broker/rest/domain/:name/applications |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/domain/mydomain/applications --user user@example.com:password
The API returns a list of all applications under the specified domain. The related resource links returned by the API have been left out for brevity. See Chapter 11, Applications for a description of each response parameter associated with an application.
{ "api_version": 1.6, "data": [ { "aliases": [], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-20T07:21:50Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": {}, "mysql-5.5": { "connection_url": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/", "username": "adminxcYKabL", "password": "IgsS3_wQYF38", "database_name": "myapp", "info": "Connection URL: mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } }, "framework": "php-5.4", "gear_count": 2, "gear_profile": "medium", "git_url": "ssh://5213190e2587c8817a000121@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health_check.php", "id": "5213190e2587c8817a000121", "initial_git_url": null, "links": { }, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "520bd6bbdbd93c3dee00000d", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://5213190e2587c8817a000121@myapp-mydomain.rhcloud.com" } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Found 1 applications." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "applications", "version": "1.6" }
11.6. List Applications and Cartridges
Get a list of all applications for the specified domain including all cartridges.
Method | URL Structure |
---|---|
GET | /broker/rest/domain/:name/applications?include=cartridges |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/domains/mydomain/applications?include=cartridges --user user@example.com
The API returns a list of all applications and embedded cartridges. The related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for a description of each response parameter associated with an application.
{ "api_version": 1.6, "data": [ { "aliases": [], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "cartridges": [ { "additional_gear_storage": 0, "base_gear_storage": 1, "collocated_with": [ "haproxy-1.4" ], "current_scale": 1, "description": "PHP is a general-purpose server-side scripting language originally designed for Web development to produce dynamic Web pages. Popular development frameworks include: CakePHP, Zend, Symfony, and Code Igniter.", "display_name": "PHP 5.4", "gear_profile": "medium", "help_topics": {}, "license": "The PHP License, version 3.0", "license_url": "http://www.php.net/license/3_0.txt", "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "520bd6bbdbd93c3dee00000d", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://5213190e2587c8817a000121@myapp-mydomain.rhcloud.com" } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Found 1 applications." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "applications", "version": "1.6" }
11.7. Get Application Information
Get information about an existing application.
Method | URL Structure |
---|---|
GET | /broker/rest/application/:id |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/52131ae36cec0e0d5f00012b
The API returns information about the specified application and related resource links which have been left out for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": [ { "aliases": [], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-20T07:29:39Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": {}, "mysql-5.5": { "connection_url": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/", "username": "adminF3x1YFi", "password": "vja3unpGDueg", "database_name": "myapp", "info": "Connection URL: mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } }, "framework": "php-5.4", "gear_count": 2, "gear_profile": "medium", "git_url": "ssh://52131ae36cec0e0d5f00012b@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health_check.php", "id": "52131ae36cec0e0d5f00012b", "initial_git_url": null, "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/applications/52131ae36cec0e0d5f00012b", "method": "GET", "optional_params": [], "rel": "Get application", "required_params": [] }, }, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "52054aef03ef64101000000d", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://52131ae36cec0e0d5f00012b@myapp-mydomain.rhcloud.com" } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Found 1 applications." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "applications", "version": "1.6" }
11.8. Get Application and Cartridge Information
Get information about an existing application and its embedded cartridges.
Method | URL Structure |
---|---|
GET | /broker/rest/application/:id?include=cartridges |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/5213190e2587c8817a000121?include=cartridges --user user@example.com
The API returns information about the specified application and its embedded cartridges. The related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "cartridges": [ { "additional_gear_storage": 0, "base_gear_storage": 1, "collocated_with": [ "haproxy-1.4" ], "current_scale": 1, "description": "PHP is a general-purpose server-side scripting language originally designed for Web development to produce dynamic Web pages. Popular development frameworks include: CakePHP, Zend, Symfony, and Code Igniter.", "display_name": "PHP 5.4", "gear_profile": "medium", "help_topics": {}, "license": "The PHP License, version 3.0", "license_url": "http://www.php.net/license/3_0.txt", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/applications/5213190e2587c8817a000121/cartridge/php-5.4", "method": "GET", "optional_params": [], "rel": "Get cartridge", "required_params": [] }, "UPDATE": { "href": "https://openshift.redhat.com/broker/rest/applications/5213190e2587c8817a000121/cartridge/php-5.4", "method": "PUT", "optional_params": [ { "default_value": null, "description": "Additional filesystem storage in gigabytes on each gear having cartridge php-5.4", "name": "additional_gear_storage", "type": "integer", "valid_options": [] }, { "default_value": null, "description": "Minimum number of gears having cartridge php-5.4", "name": "scales_from", "type": "integer", "valid_options": [] }, { "default_value": null, "description": "Maximum number of gears having cartridge php-5.4", "name": "scales_to", "type": "integer", "valid_options": [] } ], "rel": "Update cartridge configuration", "required_params": [] }, ........ "name": "php-5.4", "properties": [ { "name": "OPENSHIFT_TMP_DIR", "type": "environment", "description": "Directory to store application temporary files." }, ........ ], "scales_from": 1, "scales_to": -1, "scales_with": "haproxy-1.4", "status_messages": null, "supported_scales_from": 1, "supported_scales_to": -1, "tags": [ "service", "php", "web_framework" ], "type": "standalone", "url": null, "usage_rates": [], "version": "5.4", "website": "http://www.php.net" }, { "additional_gear_storage": 0, "base_gear_storage": 1, "collocated_with": [ "php-5.4" ], "current_scale": 1, "description": "Acts as a load balancer for your web cartridge and will automatically scale up to handle incoming traffic. Is automatically added to scaled applications when they are created and cannot be removed or added to an application after the fact.", "display_name": "OpenShift Web Balancer", "gear_profile": "medium", "help_topics": {}, "license": "GPLv2+", "license_url": "http://www.gnu.org/licenses/gpl-2.0.html", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/applications/5213190e2587c8817a000121/cartridge/haproxy-1.4", "method": "GET", "optional_params": [], "rel": "Get cartridge", "required_params": [] }, ........ "name": "mysql-5.5", "properties": [ { "name": "username", "type": "cart_data", "description": "Root user on mysql database", "value": "adminxcYKabL" }, { "name": "password", "type": "cart_data", "description": "Password for root user on mysql database", "value": "IgsS3_wQYF38" }, { "name": "database_name", "type": "cart_data", "description": "MySQL DB name", "value": "myapp" }, { "name": "connection_url", "type": "cart_data", "description": "MySQL DB connection URL", "value": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } ], "scales_from": 1, "scales_to": 1, "scales_with": "haproxy-1.4", "status_messages": null, "supported_scales_from": 1, "supported_scales_to": 1, "tags": [ "service", "database", "embedded" ], "type": "embedded", "url": null, "usage_rates": [], "version": "5.5", "website": "http://www.mysql.com" } ], ........ "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "520bd6bbdbd93c3dee00000d", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://5213190e2587c8817a000121@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application 'myapp' found" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.9. Update an Application
Update an application.
Method | Resource URL |
---|---|
PUT | /broker/rest/application/:id |
Name | Description | Required | Default Value |
---|---|---|---|
auto_deploy | Indicates whether an application should build and deploy automatically whenever git push is executed | No | |
deployment_type | Indicates whether an application is configured for binary or Git based deployments | No | |
deployment_branch | If automatic deployment is enabled, this indicates from which branch automatic deployment occurs | No | |
keep_deployments | Indicates how many total deployments are preserved; must be greater than zero | No |
{ "auto_deploy": true, "deployment_type": "git" }
$ curl -X PUT https://openshift.redhat.com/broker/rest/application/527ade9d7f9c48d37100000a --user user@myemail.com:password --data-urlencode auto_deploy=true --data-urlencode deployment_type=git
The API returns the deployment resource. See Chapter 11, Applications for more information on all deployment parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapplication-mydomain.rhcloud.com/", "auto_deploy": true, "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-11-07T00:28:13Z", "deployment_branch": "master", "deployment_type": "git", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://527ade9d7f9c48d37100000a@myapplication-mydomain.rhcloud.com/~/git/myapplication.git/", "health_check_path": "health", "id": "527ade9d7f9c48d37100000a", "initial_git_url": null, "keep_deployments": 1, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "527ade897f9c48d371000001", "login": "user@myemail.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapplication", "scalable": true, "ssh_url": "ssh://527ade9d7f9c48d37100000a@myapplication-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Application myapplication was updated." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.10. Enable High Availability (HA) on Application
Enable high availability (HA) feature on an application.
Method | URL Structure |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "make-ha" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/527ade9d7f9c48d37100000a/events --user user@example.com:password --data-urlencode event=make-ha
11.11. Disable High Availability (HA) on Application
Disable high availability (HA) feature on an application.
Method | URL Structure |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "disable-ha" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/527ade9d7f9c48d37100000a/events --user user@example.com:password --data-urlencode event=disable-ha
11.12. Start Application
Start an application that is not running.
Method | URL Structure |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "start" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com:password --data-urlencode event=start
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp has started" }, { "exit_code": 0, "field": null, "severity": "warning", "text": "HAProxy instance is started\n" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.13. Stop Application
Stop a running application.
Method | URL Structure |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "stop" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=stop
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp has stopped" }, { "exit_code": 0, "field": null, "severity": "warning", "text": "HAProxy instance is stopped\n" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.14. Force Stop Application
Force a running application to stop.
Method | URL Structure |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "force-stop" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com:password --data-urlencode event=force-stop
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity.See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp has forcefully stopped" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.15. Restart Application
Restart a running application.
Method | URL Structure |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "restart" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com:password --data-urlencode event=restart
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp has restarted" }, { "exit_code": 0, "field": null, "severity": "warning", "text": "Restarted HAProxy instance\n" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.16. Scale Up Application
Scale up an application that was created with the scaling function enabled.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "scale-up" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=scale-up
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 2, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp has scaled up" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
{ "status": "unprocessable_entity", "messages": [ { "field": null, "text": "user@example.com has already reached the gear limit of 3", "severity": "error", "exit_code": 104 } ] }
11.17. Scale Down Application
Scale down an application that was created with the scaling function enabled.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "scale-down" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=scale-down
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp has scaled down" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
{ "status": "unprocessable_entity", "messages": [ { "field": null, "text": "Failed to add event scale-down to application myapp due to: Cannot scale below minimum gear requirements for group '1'", "severity": "error", "exit_code": 1 } ] }
11.18. Tidy Application Framework
Tidy the application framework.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "tidy" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=tidy
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp called tidy" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.19. Reload Application
Reload an application.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "reload" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=reload
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application myapp called reload" }, { "exit_code": 0, "field": null, "severity": "warning", "text": "Reloaded HAProxy instance\n" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.20. Trigger Thread Dump
Trigger application thread dump.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "thread-dump" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=thread-dump
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "" }, { "exit_code": 0, "field": null, "severity": "result", "text": "Success\nThe thread dump file will be available via: rhc tail myapp -f /var/lib/openshift/534253991015616165707776/ruby//logs//error_log-20130821-* -o '-n 250'\n" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
11.21. Delete Application
Delete an OpenShift application.
Method | Resource URL |
---|---|
DELETE | /broker/rest/application/:id |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/application/534253991015616165707776 -user user@example.com
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Application 534253991015616165707776 is deleted." } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
Chapter 12. Application Aliases and SSL Certificates
Name | Description |
---|---|
id | Name of application alias. |
certificate_added_at | The date and time when the SSL certificate was added. |
has_private_ssl_certificate | Indicates whether an SSL certificate has been added to the specified application. |
12.1. Add Application Alias
Add an alias to an application, with the option to upload an SSL certificate. Adding an alias allows you to use your own domain name for an application.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/aliases |
Name | Description | Required | Default |
---|---|---|---|
id | Alias for application | Yes | |
ssl_certificate | Content of SSL certificate | No | |
private_key | Required private key for SSL certificate | No | |
pass_phrase | Optional passphrase for private key | No |
{ "id": "myappalias", "ssl_certificate": "-----BEGIN CERTIFICATE-----\nMIIDoDCCAogCCQDzF8AJCHnrbjANBgkqhkiG9w0BAQUFADCBkTELMAkGA1UEBhMC\nVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJl\nZGhhdDESMBAGA1UECwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAm\nBgkqhkiG9w0BCQEWGWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wHhcNMTMwMjE5\nMjExMTQ4WhcNMTQwMjE5MjExMTQ4WjCBkTELMAkGA1UEBhMCVVMxCzAJBgNVBAgM\nAkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJlZGhhdDESMBAGA1UE\nCwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAmBgkqhkiG9w0BCQEW\nGWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB\nDwAwggEKAoIBAQDAEbH4MCi3iIDP1HS+/Xwu8SjdSc5WJX6htV7hJpmFZ8HohV/8\nba0v6aM9IJIIt+sIe2J62t/9G3leOdIHBxeACN4fV2l/iA/fvxvlnFKeD7sHm9Oc\nYj1H6YYJ57sIOf/oLDpJl6l3Rw8VC3+3W0/lzlVpA8qt7fpkiW7XQJCPplUSrdVC\n3okQ2T5NAod5+wVIOqELgE5bLX1LRs5VPsjytHkJ7rKXs55FHR3kpsoImn5xD0Ky\n6lRn8cIMolQoyN5HIGr8f5P+07hrHibve8jje/DKTssb5yEUAEmh6iGHQsRAnsUW\nQoIEUOLqQCu9re2No4G52Kl2xQIjyJF7rCfxAgMBAAEwDQYJKoZIhvcNAQEFBQAD\nggEBAGHrya/ZkiAje2kHsOajXMlO2+y1iLfUDcRLuEWpUa8sI5EM4YtemQrsupFp\n8lVYG5C4Vh8476oF9t8Wex5eH3ocwbSvPIUqE07hdmrubiMq4wxFVRYq7g9lHAnx\nl+bABuN/orbAcPcGAGg7AkXVoAc3Fza/ZcgMcw7NOtDTEss70V9OdgCfQUJL0KdO\nhCO8bQ1EaEiq6zEh8RpZe8mu+f/GYATX1I+eJUc6F6cn83oJjE9bqAVzk7TzTHeK\nEBKN50C14wWtXeG7n2+ugaVO+0xnvHeUrQBLHSRyOHqxXrQQ5XmzcaBiyI0f2IQM\nHst1BVXyX0n/L/ZoYYsv5juJmDo=\n-----END CERTIFICATE-----", "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAwBGx+DAot4iAz9R0vv18LvEo3UnOViV+obVe4SaZhWfB6IVf\n/G2tL+mjPSCSCLfrCHtietrf/Rt5XjnSBwcXgAjeH1dpf4gP378b5ZxSng+7B5vT\nnGI9R+mGCee7CDn/6Cw6SZepd0cPFQt/t1tP5c5VaQPKre36ZIlu10CQj6ZVEq3V\nQt6JENk+TQKHefsFSDqhC4BOWy19S0bOVT7I8rR5Ce6yl7OeRR0d5KbKCJp+cQ9C\nsupUZ/HCDKJUKMjeRyBq/H+T/tO4ax4m73vI43vwyk7LG+chFABJoeohh0LEQJ7F\nFkKCBFDi6kArva3tjaOBudipdsUCI8iRe6wn8QIDAQABAoIBAG/on4JVRRQSw8LU\nLiWt+jI7ryyoOUH2XL8JtzuGSwLwvomlVJT2rmbxQXx3Qr8zsgziHzIn30RRQrkF\nBXu0xRuDjzBBtSVqeJ1Mc4uoNncEAVxgjb5bewswZDnXPCGB8bosMtX4OPRXgdEo\nPwTtfjMOsrMaU3hd5Xu4m81tQA2BvwOlx8aYDyH0jeTnervc5uRGbeTBQG4Bu40E\nrWNmXvgNq2EzTAwbbN6Ma97gw9KgXnM4Nlh29Fxb5TBeUU9lkzuTZAZIDXKIm7AG\nUwMbj/A038yAumYQtThTE/3e4W3rn7F2Vko900bC4aAC1KQOAzjIeQqzqkVxWTWq\n4SUFQAECgYEA/ODwifOTuI6hdZK6JRgc4wp6Rc0fkqHuxLzABXoIGuSVlWyimqIN\nZySAkpo5EW6DNraRJxNCOBmWeGPEhHGrea+JPiPEwCK0F7SxvSmg3jzNzw3Es31T\necET7eDwuSOY9v4XDzLyiXXkEUUReD7Ng2hEYL+HaQrl5jWj4lxgq/ECgYEAwnCb\nKrz7FwX8AqtFAEi6uUrc12k1xYKQfrwSxbfdK2vBBUpgB71Iq/fqP+1BittEljDG\n8f4jEtMBFfEPhLzGIHaI3UiHUHXS4GetA77TRgR8lnKKpj1FcMIY2iKU479707O5\nQ08pgWRUDQ8BVg2ePgbo5QjLMc/rv7UF3AHvPAECgYB/auAIwqDGN6gHU/1TP4ke\npWLi1O55tfpXSzv+BnUbB96PQgPUop7aP7xBIlBrBiI7aVZOOBf/qHT3CF421geu\n8tHWa7NxlIrl/vgn9lfGYyDYmXlpb1amXLEsBVGGF/e1TGZWFDe9J5fZU9HvosVu\n1xTNIvSZ6xHYI2MGZcGYIQKBgEYeebaV5C7PV6xWu1F46O19U9rS9DM//H/XryVi\nQv4vo7IWuj7QQe7SPsXC98ntfPR0rqoCLf/R3ChfgGsr8H8wf/bc+v9HHj8S5E/f\ndy1e3Nccg2ej3PDm7jNsGSlwmmUkAQGHAL7KwYzcBm1UB+bycvZ1j2FtS+UckPpg\nMDgBAoGALD8PkxHb4U4DtbNFSYRrUdvS9heav/yph3lTMfifNkOir36io6v8RPgb\nD2bHKKZgmYlTgJrxD45Er9agC5jclJO35QRU/OfGf3GcnABkBI7vlvUKADAo65Sq\nweZkdJnbrIadcvLOHOzkKC9m+rxFTC9VoN1dwK2zwYvUXfa1VJA=\n-----END RSA PRIVATE KEY-----", "pass_phrase": "abcd" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases --user user@example.com --data-urlencode id=myappalias
When adding an alias an SSL certificate can also be uploaded to allow secure HTTPS communication with an application. To upload an SSL certificate include the required private key with or without the optional private key passphrase. This can be done by cutting and pasting the contents of the SSL certificate and the key.
$ curl -X POST https://openshift.redhat.com/broker/rest/applications/534253991015616165707776/aliases --user user@example.com --data-urlencode id=myappalias --data-urlencode ssl_certificate=-----BEGIN CERTIFICATE----- MIIDoDCCAogCCQDzF8AJCHnrbjANBgkqhkiG9w0BAQUFADCBkTELMAkGA1UEBhMC VVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJl ZGhhdDESMBAGA1UECwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAm BgkqhkiG9w0BCQEWGWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wHhcNMTMwMjE5 MjExMTQ4WhcNMTQwMjE5MjExMTQ4WjCBkTELMAkGA1UEBhMCVVMxCzAJBgNVBAgM AkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJlZGhhdDESMBAGA1UE CwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAmBgkqhkiG9w0BCQEW GWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB DwAwggEKAoIBAQDAEbH4MCi3iIDP1HS+/Xwu8SjdSc5WJX6htV7hJpmFZ8HohV/8 ba0v6aM9IJIIt+sIe2J62t/9G3leOdIHBxeACN4fV2l/iA/fvxvlnFKeD7sHm9Oc Yj1H6YYJ57sIOf/oLDpJl6l3Rw8VC3+3W0/lzlVpA8qt7fpkiW7XQJCPplUSrdVC 3okQ2T5NAod5+wVIOqELgE5bLX1LRs5VPsjytHkJ7rKXs55FHR3kpsoImn5xD0Ky 6lRn8cIMolQoyN5HIGr8f5P+07hrHibve8jje/DKTssb5yEUAEmh6iGHQsRAnsUW QoIEUOLqQCu9re2No4G52Kl2xQIjyJF7rCfxAgMBAAEwDQYJKoZIhvcNAQEFBQAD ggEBAGHrya/ZkiAje2kHsOajXMlO2+y1iLfUDcRLuEWpUa8sI5EM4YtemQrsupFp 8lVYG5C4Vh8476oF9t8Wex5eH3ocwbSvPIUqE07hdmrubiMq4wxFVRYq7g9lHAnx l+bABuN/orbAcPcGAGg7AkXVoAc3Fza/ZcgMcw7NOtDTEss70V9OdgCfQUJL0KdO hCO8bQ1EaEiq6zEh8RpZe8mu+f/GYATX1I+eJUc6F6cn83oJjE9bqAVzk7TzTHeK EBKN50C14wWtXeG7n2+ugaVO+0xnvHeUrQBLHSRyOHqxXrQQ5XmzcaBiyI0f2IQM Hst1BVXyX0n/L/ZoYYsv5juJmDo= -----END CERTIFICATE----- --data-urlencode private_key=-----BEGIN RSA PRIVATE KEY----- MIIEogIBAAKCAQEAwBGx+DAot4iAz9R0vv18LvEo3UnOViV+obVe4SaZhWfB6IVf /G2tL+mjPSCSCLfrCHtietrf/Rt5XjnSBwcXgAjeH1dpf4gP378b5ZxSng+7B5vT nGI9R+mGCee7CDn/6Cw6SZepd0cPFQt/t1tP5c5VaQPKre36ZIlu10CQj6ZVEq3V Qt6JENk+TQKHefsFSDqhC4BOWy19S0bOVT7I8rR5Ce6yl7OeRR0d5KbKCJp+cQ9C supUZ/HCDKJUKMjeRyBq/H+T/tO4ax4m73vI43vwyk7LG+chFABJoeohh0LEQJ7F FkKCBFDi6kArva3tjaOBudipdsUCI8iRe6wn8QIDAQABAoIBAG/on4JVRRQSw8LU LiWt+jI7ryyoOUH2XL8JtzuGSwLwvomlVJT2rmbxQXx3Qr8zsgziHzIn30RRQrkF BXu0xRuDjzBBtSVqeJ1Mc4uoNncEAVxgjb5bewswZDnXPCGB8bosMtX4OPRXgdEo PwTtfjMOsrMaU3hd5Xu4m81tQA2BvwOlx8aYDyH0jeTnervc5uRGbeTBQG4Bu40E rWNmXvgNq2EzTAwbbN6Ma97gw9KgXnM4Nlh29Fxb5TBeUU9lkzuTZAZIDXKIm7AG UwMbj/A038yAumYQtThTE/3e4W3rn7F2Vko900bC4aAC1KQOAzjIeQqzqkVxWTWq 4SUFQAECgYEA/ODwifOTuI6hdZK6JRgc4wp6Rc0fkqHuxLzABXoIGuSVlWyimqIN ZySAkpo5EW6DNraRJxNCOBmWeGPEhHGrea+JPiPEwCK0F7SxvSmg3jzNzw3Es31T ecET7eDwuSOY9v4XDzLyiXXkEUUReD7Ng2hEYL+HaQrl5jWj4lxgq/ECgYEAwnCb Krz7FwX8AqtFAEi6uUrc12k1xYKQfrwSxbfdK2vBBUpgB71Iq/fqP+1BittEljDG 8f4jEtMBFfEPhLzGIHaI3UiHUHXS4GetA77TRgR8lnKKpj1FcMIY2iKU479707O5 Q08pgWRUDQ8BVg2ePgbo5QjLMc/rv7UF3AHvPAECgYB/auAIwqDGN6gHU/1TP4ke pWLi1O55tfpXSzv+BnUbB96PQgPUop7aP7xBIlBrBiI7aVZOOBf/qHT3CF421geu 8tHWa7NxlIrl/vgn9lfGYyDYmXlpb1amXLEsBVGGF/e1TGZWFDe9J5fZU9HvosVu 1xTNIvSZ6xHYI2MGZcGYIQKBgEYeebaV5C7PV6xWu1F46O19U9rS9DM//H/XryVi Qv4vo7IWuj7QQe7SPsXC98ntfPR0rqoCLf/R3ChfgGsr8H8wf/bc+v9HHj8S5E/f dy1e3Nccg2ej3PDm7jNsGSlwmmUkAQGHAL7KwYzcBm1UB+bycvZ1j2FtS+UckPpg MDgBAoGALD8PkxHb4U4DtbNFSYRrUdvS9heav/yph3lTMfifNkOir36io6v8RPgb D2bHKKZgmYlTgJrxD45Er9agC5jclJO35QRU/OfGf3GcnABkBI7vlvUKADAo65Sq weZkdJnbrIadcvLOHOzkKC9m+rxFTC9VoN1dwK2zwYvUXfa1VJA= -----END RSA PRIVATE KEY----- --data-urlencode pass_phrase=abcd
The API returns the aliases resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 12, Application Aliases and SSL Certificates for all parameters associated with application aliases.
{ "api_version": 1.6, "data": { "certificate_added_at": "2013-08-20T00:00:00Z", "has_private_ssl_certificate": true, "id": "myappalias" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Added myappalias to application myapp" } ], "status": "created", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "alias", "version": "1.6" }
12.2. List Application Aliases
List all aliases and SSL certificates associated with the specified application.
Note
Method | URL Structure |
---|---|
GET | /broker/rest/application/:id/aliases |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases --user user@example.com
The API returns a list of all aliases and SSL certificates for the specified application. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 12, Application Aliases and SSL Certificates for a description of each response parameter associated with application aliases.
{ "api_version": 1.6, "data": [ ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Listing aliases for application myapp under domain mydomain" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "alias", "version": "1.6" }
12.3. Get Application Alias Information
Get information about the specified application alias.
Note
Method | URL Structure |
---|---|
GET | /broker/rest/application/:id/aliases/:id |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases/myappalias --user user@example.com
The API returns information about the specified alias. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 12, Application Aliases and SSL Certificates for a description of each response parameter associated with application aliases.
{ "api_version": 1.6, "data": { "certificate_added_at": "2013-08-20T00:00:00Z", "has_private_ssl_certificate": true, "id": "myappalias" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Showing alias myappalias for application myapp under domain mydomain" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "alias", "version": "1.6" }
12.4. Update Application Alias
Update an existing application alias with a new SSL certificate or remove an existing certificate.
Method | Resource URL |
---|---|
PUT | /broker/rest/application/:id/aliases/:id |
Name | Description | Required | Default |
---|---|---|---|
ssl_certificate | Content of SSL certificate | Yes | |
private_key | Required private key for SSL certificate | Yes | |
pass_phrase | Optional passphrase for private key | No |
{ "ssl_certificate": "-----BEGIN CERTIFICATE-----\nMIIDoDCCAogCCQDzF8AJCHnrbjANBgkqhkiG9w0BAQUFADCBkTELMAkGA1UEBhMC\nVVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJl\nZGhhdDESMBAGA1UECwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAm\nBgkqhkiG9w0BCQEWGWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wHhcNMTMwMjE5\nMjExMTQ4WhcNMTQwMjE5MjExMTQ4WjCBkTELMAkGA1UEBhMCVVMxCzAJBgNVBAgM\nAkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJlZGhhdDESMBAGA1UE\nCwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAmBgkqhkiG9w0BCQEW\nGWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB\nDwAwggEKAoIBAQDAEbH4MCi3iIDP1HS+/Xwu8SjdSc5WJX6htV7hJpmFZ8HohV/8\nba0v6aM9IJIIt+sIe2J62t/9G3leOdIHBxeACN4fV2l/iA/fvxvlnFKeD7sHm9Oc\nYj1H6YYJ57sIOf/oLDpJl6l3Rw8VC3+3W0/lzlVpA8qt7fpkiW7XQJCPplUSrdVC\n3okQ2T5NAod5+wVIOqELgE5bLX1LRs5VPsjytHkJ7rKXs55FHR3kpsoImn5xD0Ky\n6lRn8cIMolQoyN5HIGr8f5P+07hrHibve8jje/DKTssb5yEUAEmh6iGHQsRAnsUW\nQoIEUOLqQCu9re2No4G52Kl2xQIjyJF7rCfxAgMBAAEwDQYJKoZIhvcNAQEFBQAD\nggEBAGHrya/ZkiAje2kHsOajXMlO2+y1iLfUDcRLuEWpUa8sI5EM4YtemQrsupFp\n8lVYG5C4Vh8476oF9t8Wex5eH3ocwbSvPIUqE07hdmrubiMq4wxFVRYq7g9lHAnx\nl+bABuN/orbAcPcGAGg7AkXVoAc3Fza/ZcgMcw7NOtDTEss70V9OdgCfQUJL0KdO\nhCO8bQ1EaEiq6zEh8RpZe8mu+f/GYATX1I+eJUc6F6cn83oJjE9bqAVzk7TzTHeK\nEBKN50C14wWtXeG7n2+ugaVO+0xnvHeUrQBLHSRyOHqxXrQQ5XmzcaBiyI0f2IQM\nHst1BVXyX0n/L/ZoYYsv5juJmDo=\n-----END CERTIFICATE-----", "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEAwBGx+DAot4iAz9R0vv18LvEo3UnOViV+obVe4SaZhWfB6IVf\n/G2tL+mjPSCSCLfrCHtietrf/Rt5XjnSBwcXgAjeH1dpf4gP378b5ZxSng+7B5vT\nnGI9R+mGCee7CDn/6Cw6SZepd0cPFQt/t1tP5c5VaQPKre36ZIlu10CQj6ZVEq3V\nQt6JENk+TQKHefsFSDqhC4BOWy19S0bOVT7I8rR5Ce6yl7OeRR0d5KbKCJp+cQ9C\nsupUZ/HCDKJUKMjeRyBq/H+T/tO4ax4m73vI43vwyk7LG+chFABJoeohh0LEQJ7F\nFkKCBFDi6kArva3tjaOBudipdsUCI8iRe6wn8QIDAQABAoIBAG/on4JVRRQSw8LU\nLiWt+jI7ryyoOUH2XL8JtzuGSwLwvomlVJT2rmbxQXx3Qr8zsgziHzIn30RRQrkF\nBXu0xRuDjzBBtSVqeJ1Mc4uoNncEAVxgjb5bewswZDnXPCGB8bosMtX4OPRXgdEo\nPwTtfjMOsrMaU3hd5Xu4m81tQA2BvwOlx8aYDyH0jeTnervc5uRGbeTBQG4Bu40E\nrWNmXvgNq2EzTAwbbN6Ma97gw9KgXnM4Nlh29Fxb5TBeUU9lkzuTZAZIDXKIm7AG\nUwMbj/A038yAumYQtThTE/3e4W3rn7F2Vko900bC4aAC1KQOAzjIeQqzqkVxWTWq\n4SUFQAECgYEA/ODwifOTuI6hdZK6JRgc4wp6Rc0fkqHuxLzABXoIGuSVlWyimqIN\nZySAkpo5EW6DNraRJxNCOBmWeGPEhHGrea+JPiPEwCK0F7SxvSmg3jzNzw3Es31T\necET7eDwuSOY9v4XDzLyiXXkEUUReD7Ng2hEYL+HaQrl5jWj4lxgq/ECgYEAwnCb\nKrz7FwX8AqtFAEi6uUrc12k1xYKQfrwSxbfdK2vBBUpgB71Iq/fqP+1BittEljDG\n8f4jEtMBFfEPhLzGIHaI3UiHUHXS4GetA77TRgR8lnKKpj1FcMIY2iKU479707O5\nQ08pgWRUDQ8BVg2ePgbo5QjLMc/rv7UF3AHvPAECgYB/auAIwqDGN6gHU/1TP4ke\npWLi1O55tfpXSzv+BnUbB96PQgPUop7aP7xBIlBrBiI7aVZOOBf/qHT3CF421geu\n8tHWa7NxlIrl/vgn9lfGYyDYmXlpb1amXLEsBVGGF/e1TGZWFDe9J5fZU9HvosVu\n1xTNIvSZ6xHYI2MGZcGYIQKBgEYeebaV5C7PV6xWu1F46O19U9rS9DM//H/XryVi\nQv4vo7IWuj7QQe7SPsXC98ntfPR0rqoCLf/R3ChfgGsr8H8wf/bc+v9HHj8S5E/f\ndy1e3Nccg2ej3PDm7jNsGSlwmmUkAQGHAL7KwYzcBm1UB+bycvZ1j2FtS+UckPpg\nMDgBAoGALD8PkxHb4U4DtbNFSYRrUdvS9heav/yph3lTMfifNkOir36io6v8RPgb\nD2bHKKZgmYlTgJrxD45Er9agC5jclJO35QRU/OfGf3GcnABkBI7vlvUKADAo65Sq\nweZkdJnbrIadcvLOHOzkKC9m+rxFTC9VoN1dwK2zwYvUXfa1VJA=\n-----END RSA PRIVATE KEY-----", "pass_phrase": "abcd" }
When updating an application alias to upload a new SSL certificate, include the contents of the SSL certificate and the associated private key with or without the optional private key passphrase.
$ curl -X PUT https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases/myappalias --user user@example.com --data-urlencode ssl_certificate=-----BEGIN CERTIFICATE----- MIIDoDCCAogCCQDzF8AJCHnrbjANBgkqhkiG9w0BAQUFADCBkTELMAkGA1UEBhMC VVMxCzAJBgNVBAgMAkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJl ZGhhdDESMBAGA1UECwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAm BgkqhkiG9w0BCQEWGWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wHhcNMTMwMjE5 MjExMTQ4WhcNMTQwMjE5MjExMTQ4WjCBkTELMAkGA1UEBhMCVVMxCzAJBgNVBAgM AkNBMRIwEAYDVQQHDAlTdW5ueXZhbGUxDzANBgNVBAoMBnJlZGhhdDESMBAGA1UE CwwJb3BlbnNoaWZ0MRIwEAYDVQQDDAlvcGVuc2hpZnQxKDAmBgkqhkiG9w0BCQEW GWluZm9Ab3BlbnNoaWZ0LnJlZGhhdC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IB DwAwggEKAoIBAQDAEbH4MCi3iIDP1HS+/Xwu8SjdSc5WJX6htV7hJpmFZ8HohV/8 ba0v6aM9IJIIt+sIe2J62t/9G3leOdIHBxeACN4fV2l/iA/fvxvlnFKeD7sHm9Oc Yj1H6YYJ57sIOf/oLDpJl6l3Rw8VC3+3W0/lzlVpA8qt7fpkiW7XQJCPplUSrdVC 3okQ2T5NAod5+wVIOqELgE5bLX1LRs5VPsjytHkJ7rKXs55FHR3kpsoImn5xD0Ky 6lRn8cIMolQoyN5HIGr8f5P+07hrHibve8jje/DKTssb5yEUAEmh6iGHQsRAnsUW QoIEUOLqQCu9re2No4G52Kl2xQIjyJF7rCfxAgMBAAEwDQYJKoZIhvcNAQEFBQAD ggEBAGHrya/ZkiAje2kHsOajXMlO2+y1iLfUDcRLuEWpUa8sI5EM4YtemQrsupFp 8lVYG5C4Vh8476oF9t8Wex5eH3ocwbSvPIUqE07hdmrubiMq4wxFVRYq7g9lHAnx l+bABuN/orbAcPcGAGg7AkXVoAc3Fza/ZcgMcw7NOtDTEss70V9OdgCfQUJL0KdO hCO8bQ1EaEiq6zEh8RpZe8mu+f/GYATX1I+eJUc6F6cn83oJjE9bqAVzk7TzTHeK EBKN50C14wWtXeG7n2+ugaVO+0xnvHeUrQBLHSRyOHqxXrQQ5XmzcaBiyI0f2IQM Hst1BVXyX0n/L/ZoYYsv5juJmDo= -----END CERTIFICATE----- --data-urlencode private_key=-----BEGIN RSA PRIVATE KEY----- MIIEogIBAAKCAQEAwBGx+DAot4iAz9R0vv18LvEo3UnOViV+obVe4SaZhWfB6IVf /G2tL+mjPSCSCLfrCHtietrf/Rt5XjnSBwcXgAjeH1dpf4gP378b5ZxSng+7B5vT nGI9R+mGCee7CDn/6Cw6SZepd0cPFQt/t1tP5c5VaQPKre36ZIlu10CQj6ZVEq3V Qt6JENk+TQKHefsFSDqhC4BOWy19S0bOVT7I8rR5Ce6yl7OeRR0d5KbKCJp+cQ9C supUZ/HCDKJUKMjeRyBq/H+T/tO4ax4m73vI43vwyk7LG+chFABJoeohh0LEQJ7F FkKCBFDi6kArva3tjaOBudipdsUCI8iRe6wn8QIDAQABAoIBAG/on4JVRRQSw8LU LiWt+jI7ryyoOUH2XL8JtzuGSwLwvomlVJT2rmbxQXx3Qr8zsgziHzIn30RRQrkF BXu0xRuDjzBBtSVqeJ1Mc4uoNncEAVxgjb5bewswZDnXPCGB8bosMtX4OPRXgdEo PwTtfjMOsrMaU3hd5Xu4m81tQA2BvwOlx8aYDyH0jeTnervc5uRGbeTBQG4Bu40E rWNmXvgNq2EzTAwbbN6Ma97gw9KgXnM4Nlh29Fxb5TBeUU9lkzuTZAZIDXKIm7AG UwMbj/A038yAumYQtThTE/3e4W3rn7F2Vko900bC4aAC1KQOAzjIeQqzqkVxWTWq 4SUFQAECgYEA/ODwifOTuI6hdZK6JRgc4wp6Rc0fkqHuxLzABXoIGuSVlWyimqIN ZySAkpo5EW6DNraRJxNCOBmWeGPEhHGrea+JPiPEwCK0F7SxvSmg3jzNzw3Es31T ecET7eDwuSOY9v4XDzLyiXXkEUUReD7Ng2hEYL+HaQrl5jWj4lxgq/ECgYEAwnCb Krz7FwX8AqtFAEi6uUrc12k1xYKQfrwSxbfdK2vBBUpgB71Iq/fqP+1BittEljDG 8f4jEtMBFfEPhLzGIHaI3UiHUHXS4GetA77TRgR8lnKKpj1FcMIY2iKU479707O5 Q08pgWRUDQ8BVg2ePgbo5QjLMc/rv7UF3AHvPAECgYB/auAIwqDGN6gHU/1TP4ke pWLi1O55tfpXSzv+BnUbB96PQgPUop7aP7xBIlBrBiI7aVZOOBf/qHT3CF421geu 8tHWa7NxlIrl/vgn9lfGYyDYmXlpb1amXLEsBVGGF/e1TGZWFDe9J5fZU9HvosVu 1xTNIvSZ6xHYI2MGZcGYIQKBgEYeebaV5C7PV6xWu1F46O19U9rS9DM//H/XryVi Qv4vo7IWuj7QQe7SPsXC98ntfPR0rqoCLf/R3ChfgGsr8H8wf/bc+v9HHj8S5E/f dy1e3Nccg2ej3PDm7jNsGSlwmmUkAQGHAL7KwYzcBm1UB+bycvZ1j2FtS+UckPpg MDgBAoGALD8PkxHb4U4DtbNFSYRrUdvS9heav/yph3lTMfifNkOir36io6v8RPgb D2bHKKZgmYlTgJrxD45Er9agC5jclJO35QRU/OfGf3GcnABkBI7vlvUKADAo65Sq weZkdJnbrIadcvLOHOzkKC9m+rxFTC9VoN1dwK2zwYvUXfa1VJA= -----END RSA PRIVATE KEY----- --data-urlencode pass_phrase=abcd
The API returns the aliases resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 12, Application Aliases and SSL Certificates for all parameters associated with application aliases.
{ "api_version": 1.6, "data": { "certificate_added_at": "2013-08-20T00:00:00Z", "has_private_ssl_certificate": true, "id": "myappalias" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Updated myappalias to application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "alias", "version": "1.6" }
12.5. Delete Application Alias
Remove an alias from an application.
Method | Resource URL |
---|---|
DELETE | /broker/rest/application/:id/aliases/:id |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases/myappalias --user user@example.com
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Removed myappalias from application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
Chapter 13. Cartridges
Standalone cartridges offer a variety of programming languages and frameworks for developing an application. Every application requires a framework cartridge. Examples include PHP, JBoss, and Ruby.
Name | Description |
---|---|
name | Name of the cartridge. |
id | Unique ID of the cartridge. |
obsolete | Indicates whether the cartridge is marked obsolete. Can be true or false . |
added_time | The date and time when the cartridge was added to an application. |
activation_time | The date and time when the cartridge version was marked active. Nil if the cartridge is not active. |
automatic_updates | Set to true if the cartridge receives updates when a security update is released. |
version | Version of the packaged software in the cartridge. |
license | License of the packaged software in the cartridge. |
license_url | URL of the license file for the packaged software in the cartridge. |
website | Website URL for the packaged software in the cartridge. |
help_topics | Map of topics and associated URLs that provide help on how to use and configure the cartridge. |
display_name | Formatted name of the cartridge for user interfaces. |
description | Description of the cartridge for user interfaces. |
current_scale | Current number of gears used to run the cartridge. |
scales_from | Minimum number of gears that a cartridge can scale to; once reached, scale_down requests are rejected. Cannot be less than the supported_scales_from value. |
scales_to | Maximum number of gears that a cartridge can scale to; once reached, scale_up requests are rejected. Cannot be greater than the supported_scales_to value. |
scales_with | Names of other cartridges that scale with this cartridge and run on the same set of gears; currently only HAProxy-1.4 is available. |
supported_scales_from | Minimum number of gears supported by the cartridge; the scales_from value cannot be less than this number. |
supported_scales_to | Maximum number of gears supported by the cartridge; the scales_to value cannot be greater than this number. |
tags | Array of tags associated with the cartridge. |
usage_rates | Plan usage costs. |
status_messages | Status messages returned by the cartridge. |
Note
scales_from
and scales_to
parameters can be set separately or set in the same REST API call. If the scales_from
value is greater than the scales_to
value, the broker logic automatically interchanges the two values.
Embedded cartridges provide extended functionality to OpenShift applications. Examples include MySQL, PostgreSQL, and Jenkins Client.
Name | Description |
---|---|
additional_gear_storage | Set additional filesystem storage in gigabytes for the gear profile that the cartridge is running on. |
base_gear_storage | Default basic storage in gigabytes associated with the gear profile that the cartridge is running on. |
collocated_with | Array of names of other cartridges that share the same gear(s) with the cartridge. |
gear_profile | Size of the gears grouped in this profile that the cartridge is running on; all gears in a group will have the same gear_profile . |
properties | List of environment variables and property values exposed by the cartridge and usable in application code. |
13.1. List Cartridges
Get a list of all available OpenShift cartridges.
Method | Resource URL |
---|---|
GET | /broker/rest/cartridges |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/cartridges --user user@example.com
The API returns the cartridge resource with a list of all available OpenShift cartridges. Information on other available cartridges has been removed for brevity. See Chapter 13, Cartridges for more information on all cartridge parameters.
{ "api_version": 1.6, "data": [ { "current_scale": 0, "description": "The Cron cartridge allows you to run command line programs at scheduled times. Use this for background jobs and periodic processing.", "display_name": "Cron 1.4", "help_topics": { "Getting Started Guide": "https://www.openshift.com/blogs/getting-started-with-cron-jobs-on-openshift" }, "license": "ASL 2.0", "license_url": "http://www.apache.org/licenses/LICENSE-2.0.txt", "name": "cron-1.4", "scales_from": 1, "scales_to": 1, "scales_with": "haproxy-1.4", "supported_scales_from": 1, "supported_scales_to": 1, "tags": [ "embedded" ], "type": "embedded", "usage_rates": [], "version": "1.4", "website": "http://www.openshift.com/" }, { "current_scale": 0, "description": "Web based MySQL admin tool. Requires the MySQL cartridge to be installed first.", "display_name": "phpMyAdmin 3.4", "help_topics": {}, "license": "GPLv2", "license_url": "", "name": "phpmyadmin-3", "scales_from": 1, "scales_to": 1, "scales_with": "haproxy-1.4", "supported_scales_from": 1, "supported_scales_to": 1, "tags": [ "embedded" ], "type": "embedded", "usage_rates": [], "version": "3", "website": "http://www.phpmyadmin.net/" }, { "current_scale": 0, "description": "Node.js is a platform built on Chrome's JavaScript runtime for easily building fast, scalable network applications. Node.js is perfect for data-intensive real-time applications that run across distributed devices.", "display_name": "Node.js 0.10", "help_topics": { "Developer Center": "https://www.openshift.com/developers" }, "license": "MIT License", "license_url": "https://raw.github.com/joyent/node/v0.6/LICENSE", "name": "nodejs-0.6", "scales_from": 1, "scales_to": -1, "scales_with": "haproxy-1.4", "supported_scales_from": 1, "supported_scales_to": -1, "tags": [ "service", "javascript", "nodejs", "web_framework" ], "type": "standalone", "usage_rates": [], "version": "0.6", "website": "http://www.nodejs.org/" }, ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "cartridges", "version": "1.6" }
13.2. Embedded Cartridges
13.2.1. Add Embedded Cartridge
Add an embedded cartridge to an application.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/cartridges |
Name | Description | Required | Default |
---|---|---|---|
name | Name of cartridge; note that valid options may be different from those shown here | Yes | |
colocate_with | Component to colocate with | No | |
scales_from | Minimum number of gears to run component | No | |
scales_to | Maximum number of gears to run component | No | |
additional_storage | Additional GB of storage request on gears running this component | No | |
gear_size | Cartridge gear size | No | |
url | URL to a downloadable cartridge | No | |
environment_variables | Add or update application environment variables | No |
{ "name": "mysql-5.5", "colocate_with": "ruby-2.0", "gear_size": "small" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridges --user "user:Password" --data-urlencode name=mysql-5.5 --data-urlencode colocate_with=ruby-2.0 --data-urlencode gear_size=small
The API returns the embedded cartridge resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 13, Cartridges for more information on all cartridge parameters.
{ "api_version": 1.6, "data": { "additional_gear_storage": 0, "base_gear_storage": 1, "collocated_with": [ "ruby-2.0", "haproxy-1.4" ], "current_scale": 1, "description": "MySQL is a multi-user, multi-threaded SQL database server.", "display_name": "MySQL Database 5.5", "gear_profile": "small", "help_topics": { }, "license": "GPL", "license_url": "", "name": "mysql-5.5", "properties": [ { "name": "username", "type": "cart_data", "description": "Root user on mysql database", "value": "adminthGnHLU" }, { "name": "password", "type": "cart_data", "description": "Password for root user on mysql database", "value": "dPFjWLrUjfxC" }, { "name": "database_name", "type": "cart_data", "description": "MySQL DB name", "value": "myapp" }, { "name": "connection_url", "type": "cart_data", "description": "MySQL DB connection URL", "value": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } ], "scales_from": 1, "scales_to": 1, "scales_with": "haproxy-1.4", "status_messages": null, "supported_scales_from": 1, "supported_scales_to": 1, "tags": [ "service", "database", "embedded" ], "type": "embedded", "url": null, "usage_rates": [ ], "version": "5.5", "website": "http://www.mysql.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Added mysql-5.5 to application myapp" }, { "exit_code": 0, "field": null, "severity": "debug", "text": "\n\nmysql-5.5: Connection URL: mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT\n" },
13.2.2. List Embedded Cartridges
Get a list of embedded cartridges that have been added to an application. For scaled applications, the API also returns the scaling properties of the cartridge.
Note
LIST_APPLICATIONS
resource. See Section 11.6, “List Applications and Cartridges” for more information.
Method | Resource URL |
---|---|
GET | /broker/rest/application/:id/cartridges |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridges --user user@example.com
The API returns a list of all embedded cartridges that have been added to the specified application. Related resource links and other cartridges returned by the API have been removed for brevity. See Chapter 13, Cartridges for more information on all cartridge parameters.
{ "api_version": 1.6, "data": [ { "additional_gear_storage": 10, "base_gear_storage": 1, "collocated_with": [ "haproxy-1.4" ], "current_scale": 1, "description": "Ruby is a dynamic, reflective, general-purpose object-oriented programming language. Popular development frameworks include Ruby on Rails and Sinatra.", "display_name": "Ruby 2.0", "gear_profile": "small", "help_topics": { }, "license": "Ruby BSDL", "license_url": "http://www.ruby-lang.org/en/about/license.txt", "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/application/527ade9d7f9c48d37100000a/cartridge/ruby-2.0", "method": "GET", "optional_params": [ ], "rel": "Get cartridge", "required_params": [ ] }, "UPDATE": { "href": "https://openshift.redhat.com/broker/rest/application/527ade9d7f9c48d37100000a/cartridge/ruby-2.0", "method": "PUT", "optional_params": [ { "default_value": null, "description": "Additional filesystem storage in gigabytes on each gear having cartridge ruby-2.0", "name": "additional_gear_storage", "type": "integer", "valid_options": [ ] }, { "default_value": null, "description": "Minimum number of gears having cartridge ruby-2.0", "name": "scales_from", "type": "integer", "valid_options": [ ] }, { "default_value": null, "description": "Maximum number of gears having cartridge ruby-2.0", "name": "scales_to", "type": "integer", "valid_options": [ ] } ], "rel": "Update cartridge configuration", "required_params": [ ........ "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "cartridges", "version": "1.6" }
13.2.3. Get Cartridge Information
Get information for the specified cartridge using the cartridge name or unique ID.
Method | Resource URL |
---|---|
GET | /broker/rest/application/:id/cartridge/:name |
Not applicable
Using the name of the cartridge:
$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5 --user user@example.com
The API returns the embedded cartridge resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 13, Cartridges for more information on all cartridge parameters.
{ "api_version": 1.6, "data": { "additional_gear_storage": 0, "base_gear_storage": 1, "collocated_with": [ "ruby-2.0", "haproxy-1.4" ], "current_scale": 1, "description": "MySQL is a multi-user, multi-threaded SQL database server.", "display_name": "MySQL Database 5.5", "gear_profile": "small", "help_topics": { }, "license": "GPL", "license_url": "", "name": "mysql-5.5", "properties": [ { "name": "username", "type": "cart_data", "description": "Root user on mysql database", "value": "adminthGnHLU" }, { "name": "password", "type": "cart_data", "description": "Password for root user on mysql database", "value": "dPFjWLrUjfxC" }, { "name": "database_name", "type": "cart_data", "description": "MySQL DB name", "value": "myapp" }, { "name": "connection_url", "type": "cart_data", "description": "MySQL DB connection URL", "value": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } ], "scales_from": 1, "scales_to": 1, "scales_with": "haproxy-1.4", "status_messages": null, "supported_scales_from": 1, "supported_scales_to": 1, "tags": [ "service", "database", "embedded" ], "type": "embedded", "url": null, "usage_rates": [ ], "version": "5.5", "website": "http://www.mysql.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Showing cartridge mysql-5.5 for application myapp under domain mydomain" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "cartridge", "version": "1.6" }
13.2.4. Update Cartridge Configuration
Update the configuration of an existing cartridge. Minimum and maximum scaling factors and additional filesystem storage in gigabytes on each gear that contains the specified cartridge can be set with this API resource.
Note
Method | Resource URL |
---|---|
PUT | /broker/rest/application/:id/cartridge/:name |
Name | Description | Required | Default |
---|---|---|---|
additional_gear_storage | Additional filesystem storage (GB) | No | |
scales_from | Minimum number of gears to run component | No | |
scales_to | Maximum number of gears to run component | No |
{ "additional_gear_storage": 10 }
$ curl -X PUT https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5 --user user@example.com --data-urlencode additional_gear_storage=10
The API returns the embedded cartridge resource with related resource links, and the updated values for the parameters that were changed. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 13, Cartridges for more information on all cartridge parameters.
{ "api_version": 1.6, "data": { "additional_gear_storage": 10, "base_gear_storage": 1, "collocated_with": [ "ruby-2.0", "haproxy-1.4" ], "current_scale": 1, "description": "MySQL is a multi-user, multi-threaded SQL database server.", "display_name": "MySQL Database 5.5", "gear_profile": "small", "help_topics": { }, "license": "GPL", "license_url": "", "name": "mysql-5.5", "properties": [ { "name": "username", "type": "cart_data", "description": "Root user on mysql database", "value": "adminthGnHLU" }, { "name": "password", "type": "cart_data", "description": "Password for root user on mysql database", "value": "dPFjWLrUjfxC" }, { "name": "database_name", "type": "cart_data", "description": "MySQL DB name", "value": "myapp" }, { "name": "connection_url", "type": "cart_data", "description": "MySQL DB connection URL", "value": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } ], "scales_from": 1, "scales_to": 1, "scales_with": "haproxy-1.4", "status_messages": null, "supported_scales_from": 1, "supported_scales_to": 1, "tags": [ "service", "database", "embedded" ], "type": "embedded", "url": null, "usage_rates": [ ], "version": "5.5", "website": "http://www.mysql.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Showing cartridge mysql-5.5 for application myapp under domain mydomain" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "cartridge", "version": "1.6" }
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 164, "field": null, "severity": "error", "text": "You are not allowed to request additional gear storage" } ], "status": "unprocessable_entity", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
13.2.5. Get Cartridge Status
Retrieve the status_messages
string as an array for the specified cartridge in an application.
Method | Resource URL |
---|---|
GET | /broker/rest/domain/:name/applications/:name/cartridge/:name |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/domain/mydomain/applications/myapp/cartridge/mysql-5.5?include=status_messages --user user@example.com
The API returns the status_messages
string as an array for the specified cartridge in an application. Unnecessary information and related resource links returned by the API have been removed for brevity.
"status_messages": [ { "gear_id": "51142f5adbd93ce16a0005c4", "message": "MySQL is running\n" } ],
13.2.6. Start Cartridge
Start an application's embedded cartridge that is not running.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/cartridge/:name/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "start" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5/events --user user@example.com --data-urlencode event=start
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { }, "mysql-5.5": { "connection_url": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/", "username": "adminthGnHLU", "password": "dPFjWLrUjfxC", "database_name": "myapp", "info": "Connection URL: mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Added start on mysql-5.5 for application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
13.2.7. Stop Cartridge
Stop an application's embedded cartridge that is running.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/cartridge/:name/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "stop" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5/events --user user@example.com --data-urlencode event=stop
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { }, "mysql-5.5": { "connection_url": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/", "username": "adminthGnHLU", "password": "dPFjWLrUjfxC", "database_name": "myapp", "info": "Connection URL: mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Added stop on mysql-5.5 for application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
13.2.8. Restart Cartridge
Restart a running embedded cartridge.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/cartridge/:name/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "restart" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5/events --user user@example.com --data-urlencode event=restart
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { }, "mysql-5.5": { "connection_url": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/", "username": "adminthGnHLU", "password": "dPFjWLrUjfxC", "database_name": "myapp", "info": "Connection URL: mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Added restart on mysql-5.5 for application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
13.2.9. Reload Cartridge
Reload the embedded cartridge configuration if it has been modified.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/cartridge/:name/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes |
{ "event": "reload" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5/events --user user@example.com --data-urlencode event=reload
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [ ], "app_url": "http://myapp-mydomain.rhcloud.com/", "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-08-21T01:58:41Z", "domain_id": "mydomain", "embedded": { "haproxy-1.4": { }, "mysql-5.5": { "connection_url": "mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/", "username": "adminthGnHLU", "password": "dPFjWLrUjfxC", "database_name": "myapp", "info": "Connection URL: mysql://$OPENSHIFT_MYSQL_DB_HOST:$OPENSHIFT_MYSQL_DB_PORT/" } }, "framework": "ruby-2.0", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health", "id": "534253991015616165707776", "initial_git_url": null, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "5213a826e499b22f15000001", "name": "user@example.com", "owner": true, "role": "admin", "type": "user" } ], "name": "myapp", "scalable": true, "ssh_url": "ssh://534253991015616165707776@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Added reload on mysql-5.5 for application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
13.2.10. Delete Cartridge
Delete an embedded cartridge from an application.
Method | Resource URL |
---|---|
DELETE | /broker/rest/application/:id/cartridge/:name |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5 --user user@example.com
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Removed mysql-5.5 from application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
Chapter 14. Deployment
Name | Description |
---|---|
id | Application deployment ID |
created_at | Creation time of application |
hot_deploy | Indicates whether the hot deployment was enabled for this deployment |
force_clean_build | Indicates whether a clean build was performed for this deployment |
ref | Git reference such as tag, branch, or commit ID |
artifact_url | A binary deployment artifact |
activations | An array of activations |
14.1. List Application Deployments
Get a list of deployments for the specified application.
Method | Resource URL |
---|---|
GET | /broker/rest/application/:id/deployments |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/5255b678b78bba421d000008/deployments --user user@example.com:password
The API returns a list of deployments for the specified application. See Chapter 14, Deployment for more information on all application deployment parameters.
{ "api_version": 1.6, "data": [ { "activations": [ "2013-10-09T20:07:35Z" ], "created_at": "2013-10-09T20:07:23Z", "force_clean_build": false, "hot_deploy": false, "id": "4e2d9a82", "ref": "master", "sha1": "86a5e8d" } ], "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Listing deployments for application myapp under domain mydomain" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "deployments", "version": "1.6" }
14.2. Deploy an Application
Deploy the specified application.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/deployments |
Name | Description | Required | Default |
---|---|---|---|
ref | Git reference, such as tag, branch, or commit ID | No | master |
artifact_url | URL from where the deployment artifact is to be downloaded | No | |
hot_deploy | Indicates whether this is a hot deployment | No | false |
force_clean_build | Indicates whether a clean build is to be performed | No | false |
{ "ref": "master", "hot_deploy": false, "force_clean_build": false }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/5255b678b78bba421d000008/deployments --user user@example.com:password --data-urlencode ref=master --data-urlencode hot_deploy=false --data-urlencode force_clean_build=false
The API returns the deployment resource. See Chapter 14, Deployment for more information on all deployment parameters.
{ "api_version": 1.6, "data": { "activations": [ "2013-10-09T20:07:16Z" ], "created_at": "2013-10-09T20:07:03Z", "force_clean_build": false, "hot_deploy": false, "id": "4e2d9a82", "ref": "master", "sha1": "86a5e8d" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Added 4e2d9a82 to application myapp" } ], "status": "created", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "deployment", "version": "1.6" }
14.3. Activate a Deployment of an Application
Activate a particular deployment for the specified application.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/events |
Name | Description | Required | Default |
---|---|---|---|
event | Event | Yes | |
deployment_id | Deployment ID to activate the application | Yes |
{ "event": "activate", "deployment_id": "f36f59c0" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/528424f6dbd93c204d000001/events --user user@example.com:password --data-urlencode event=activate --data-urlencode deployment_id=56e71f70
The API returns the application resource. Unnecessary information and related resource links returned by the API have been removed for brevity. See Chapter 11, Applications for more information on all application parameters.
{ "api_version": 1.6, "data": { "aliases": [], "app_url": "http://myapp-mydomain.rhcloud.com/", "auto_deploy": true, "build_job_url": null, "building_app": null, "building_with": null, "creation_time": "2013-11-14T01:18:46Z", "deployment_branch": "master", "deployment_type": "git", "domain_id": "mydomain", "embedded": {}, "framework": "php-5.4", "gear_count": 1, "gear_profile": "small", "git_url": "ssh://528424f6dbd93c204d000001@myapp-mydomain.rhcloud.com/~/git/myapp.git/", "health_check_path": "health_check.php", "id": "528424f6dbd93c204d000001", "initial_git_url": null, "keep_deployments": 10, "links": { "GET": { "href": "https://openshift.redhat.com/broker/rest/application/528424f6dbd93c204d000001", "method": "GET", "optional_params": [], "rel": "Get application", "required_params": [] }, }, "members": [ { "explicit_role": null, "from": [ { "type": "domain", "role": "admin" } ], "id": "520bd6bbdbd93c3dee00000d", "login": "user@example.com", "owner": true, "role": "admin", "type": "user" }, ], "name": "myapp", "scalable": false, "ssh_url": "ssh://528424f6dbd93c204d000001@myapp-mydomain.rhcloud.com" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Deployment ID 56e71f70 on application myapp has been activated" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "application", "version": "1.6" }
14.4. Update an Application Deployment
Update a deployment of an application. Note that special permissions are required to update deployments.
Method | Resource URL |
---|---|
POST | /broker/rest/application/:id/deployments |
Name | Description | Required | Default |
---|---|---|---|
deployments | An array of deployments | Yes |
$ curl -X POST https://openshift.redhat.com/broker/rest/application/5255b678b78bba421d000008/deployments --user user@example.com:password
The API returns the deployment resource. See Chapter 14, Deployment for more information on all deployment parameters.
{ "api_version": 1.6, "data": { "activations": [ "2014-03-27T07:50:10Z" ], "created_at": "2014-03-27T07:50:03Z", "force_clean_build": false, "hot_deploy": false, "id": "1823e2dc", "ref": "master", "sha1": "bcf49c4" }, "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Added 1823e2dc to application myapp" } ], "status": "created", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "deployment", "version": "1.6" }
Chapter 15. Environment Variables
Name | Description |
---|---|
name | Name of the environment variable |
value | Value of the environment variable |
15.1. Add Environment Variable
Add an environment variable to the specified application.
Method | URL Structure |
---|---|
POST | /broker/rest/application/:id/environment-variables |
Name | Description | Required | Default |
---|---|---|---|
name | Name of environment variable | No | |
value | Value of environment variable | No |
{ "name": "MY_ENV_VAR", "value": "myvalue" }
$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variables --user user@example.com:password --data-urlencode name=MY_ENV_VAR --data-urlencode value=myvalue
The API returns the environment variables resource with related resource links which have been left out for brevity. See Chapter 15, Environment Variables for more information on all parameters for environment variables.
{ "api_version": 1.6, "data": { "name": "MY_ENV_VAR", "value": "myvalue" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Added environment variable 'MY_ENV_VAR' to application myapp" } ], "status": "created", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "environment-variable", "version": "1.6" }
15.2. List Environment Variables
Get a list of all environment variables associated with the specified application.
Method | Resource URL |
---|---|
GET | /broker/rest/application/:id/environment-variables |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variables --user user@example.com
The API returns the environment variables resource with a list of all available environment variables for the specified application. Unnecessary information and other resource links have been removed for brevity. See Chapter 15, Environment Variables for more information on all parameters for environment variables.
{ "api_version": 1.6, "data": { "name": "MY_ENV_VAR", "value": "myvalue" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Showing environment variable 'MY_ENV_VAR' for application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "environment-variable", "version": "1.6" }
15.3. Get Environment Variable Information
Get information about the specified environment variable.
Method | Resource URL |
---|---|
GET | /broker/rest/application/:id/environment-variable/ENV_VAR_NAME |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variable/MY_ENV_VAR --user user@example.com
The API returns information about the specified environment variable. Unnecessary information and other resource links have been removed for brevity. See Chapter 15, Environment Variables for more information on all parameters for environment variables.
{ "api_version": 1.6, "data": { "name": "MY_ENV_VAR", "value": "myvalue" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Showing environment variable 'MY_ENV_VAR' for application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "environment-variable", "version": "1.6" }
15.4. Update Environment Variable
Update the value of an existing environment variable.
Method | URL Structure |
---|---|
PUT | /broker/rest/application/:id/environment-variable/ENV_VAR_NAME |
Name | Description | Required | Default |
---|---|---|---|
value | Value of environment variable | Yes |
{ "value": "mynewvalue" }
$ curl -X PUT https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variable/MY_ENV_VAR --user user@example.com --data-urlencode value=mynewvalue
The API returns the environment variables resource with related resource links which have been left out for brevity. See Chapter 15, Environment Variables for more information on all parameters for environment variables.
{ "api_version": 1.6, "data": { "name": "MY_ENV_VAR", "value": "mynewvalue" }, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Updated environment variable 'MY_ENV_VAR' in application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": "environment-variable", "version": "1.6" }
15.5. Delete Environment Variable
Delete an existing environment variable.
Method | Resource URL |
---|---|
DELETE | /broker/rest/application/:id/environment-variable/ENV_VAR_NAME |
Not applicable
$ curl -X DELETE https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variable/MY_ENV_VAR --user user@example.com
{ "api_version": 1.6, "data": null, "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Removed environment variable 'MY_ENV_VAR' from application myapp" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6 ], "type": null, "version": "1.6" }
Chapter 16. Gear Groups
16.1. Get Application Gear Groups
Get a list of gear groups where each group represents a list of gears that share scaling and storage policies.
Note
Method | URL Structure |
---|---|
GET | /broker/rest/application/:id/gear_groups |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/application/5213190e2587c8817a000121/gear_groups --user user@example.com
The API returns a list of all gear groups for the specified application. See Chapter 13, Cartridges for more information on all cartridge parameters.
"api_version": 1.7, "data": [ { "additional_gear_storage": 0, "base_gear_storage": 1, "cartridges": [ { "name": "haproxy-1.4", "display_name": "Web Load Balancer", "tags": [ "web_proxy", "scales", "embedded" ] }, { "name": "ruby-1.9", "display_name": "Ruby 1.9", "tags": [ "service", "ruby", "web_framework" ] } ], "gear_profile": "small", "gears": [ { "id": "53bdbd95e19923514a0000c1", "state": "started", "ssh_url": "ssh://53bdbd95e19923514a0000c1@myapp-mydomain.rhcloud.com", "region": null, "zone": null } ], "id": "53bdbd95e19923514a0000c3", "name": "53bdbd95e19923514a0000c3", "scales_from": 1, "scales_to": -1 } ], "messages": [ { "exit_code": 0, "field": null, "index": null, "severity": "info", "text": "Showing gear groups for application 'myapp' with domain 'mydomain'" }, { "exit_code": 0, "field": null, "index": null, "severity": "result", "text": "started\n" } ], "status": "ok", "supported_api_versions": [ 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7 ], "type": "gear_groups", "version": "1.7"
16.2. Get Application Gear Endpoints
Get API endpoints for individual application gears.
Method | URL Structure |
---|---|
GET | /broker/rest/applications/:id/gear_groups |
Not applicable
$ curl -X GET https://openshift.redhat.com/broker/rest/applications/5213190e2587c8817a000121/gear_groups --user user@myemail.com --data-urlencode include=endpoints
{ "include": "endpoints" }
The API returns a list of all gear groups for the specified application, including API endpoints for individual gears. Some information has been removed for brevity. See Chapter 13, Cartridges for more information on all cartridge parameters.
{ "api_version": 1.6, "data": [ { "gears": [ { "id": "5244ccb703ef64dc410000cf", "state": "started", "ssh_url": "ssh://5244ccb703ef64dc410000cf@myapp-mydomain.rhcloud.com", "endpoints": [ { "cartridge_name": "jbosseap-6", "external_address": "23.22.238.189", "external_port": "65006", "internal_address": "127.12.125.129", "internal_port": "8080", "protocols": [ "http", "ws" ], "types": [ "web_framework" ], "mappings": [ { "frontend": "", "backend": "" }, { "frontend": "/health", "backend": "" } ] }, { "cartridge_name": "jbosseap-6", "external_address": "23.22.238.189", "external_port": "65007", "internal_address": "127.12.125.129", "internal_port": "7600", "protocols": [ "tcp" ], "types": [ "web_framework" ], "mappings": [] }, { "cartridge_name": "jbosseap-6", "external_address": "23.22.238.189", "external_port": "65008", "internal_address": "127.12.125.129", "internal_port": "5445", "protocols": [ "tcp" ], "types": [ "web_framework" ], "mappings": [] }, { "cartridge_name": "jbosseap-6", "external_address": "23.22.238.189", "external_port": "65009", "internal_address": "127.12.125.129", "internal_port": "5455", "protocols": [ "tcp" ], "types": [ "web_framework" ], "mappings": [] }, { "cartridge_name": "jbosseap-6", "external_address": "23.22.238.189", "external_port": "65010", "internal_address": "127.12.125.129", "internal_port": "4447", "protocols": [ "tcp" ], "types": [ "web_framework" ], "mappings": [] } ] } ], } ], "messages": [ { "exit_code": 0, "field": null, "severity": "info", "text": "Showing gear groups for application 'myapp' with domain 'mydomain'" } ], "status": "ok", "type": "gear_groups", "version": "1.6" }
Appendix A. Valid Options for API Resources
A.1. SSH Keys
Name | Valid Options |
---|---|
name | |
type | ssh-rsa ; ssh-dss ; ecdsa-sha2-nistp256-cert-v01@openssh.com ; ecdsa-sha2-nistp384-cert-v01@openssh.com ; ecdsa-sha2-nistp521-cert-v01@openssh.com ; ssh-rsa-cert-v01@openssh.com ; ssh-dss-cert-v01@openssh.com ; ssh-rsa-cert-v00@openssh.com ; ssh-dss-cert-v00@openssh.com ; ecdsa-sha2-nistp256 ; ecdsa-sha2-nistp384 ; ecdsa-sha2-nistp521 |
content |
A.2. Authorizations
Name | Valid Options |
---|---|
scope | session ; read ; userinfo ; domain/:id/view ; domain/:id/edit ; domain/:id/admin ; application/:id/view ; application/:id/edit ; application/:id/admin |
note | |
expires_in | |
reuse | true ; false |
A.3. Domains
Name | Valid Options |
---|---|
name | |
allowed_gear_sizes | small; medium; large; c9 |
owner | User input; @self |
force |
A.4. Teams
A.5. Members
A.6. Applications
Name | Valid Options |
---|---|
name | |
cartridges | python-3.3 ; python-2.7 ; python-2.6 ; ruby-2.0 ; ruby-1.9 ; ruby-1.8 ; jenkins-1 ; jbossews-2.0 ; jbossews-1.0 ; perl-5.10 ; php-5.3 ; php-5.4 ; jbosseap-6 ; diy-0.1 |
scale | true ; false |
gear_size | small ; small.highcpu ; medium ; large |
initial_git_url | URL; empty |
cartridges[][name] | python-3.3 ; python-2.7 ; python-2.6 ; ruby-2.0 ; ruby-1.9 ; ruby-1.8 ; jenkins-1 ; jbossews-2.0 ; jbossews-1.0 ; perl-5.10 ; php-5.3 ; php-5.4 ; jbosseap-6 ; diy-0.1 |
cartridges[][gear_size] | small ; small.highcpu ; medium ; large |
cartridges[][url] | |
environment_variables | |
auto_deploy [a] | true ; false |
deployment_type [b] | git ; binary |
deployment_branch [c] | |
keep_deployments [d] | |
event | make-ha ; disable-ha ; start ; stop ; force-stop ; restart ; scale-up ; scale-down ; tidy ; reload ; thread-dump |
owner | User input; @self |
[a]
The auto_deploy option can only be set when modifying an existing application.
[b]
The deployment_type option can only be set when modifying an existing application.
[c]
The deployment_branch option can only be set when modifying an existing application.
[d]
The keep_deployments option can only be set when modifying an existing application.
|
See Also:
A.7. Cartridges
Name | Valid Options |
---|---|
name | cron-1.4 ; mysql-5.1 ; mysql-5.5 ; postgresql-9.2 ; haproxy-1.4 ; jenkins-client-1 |
colocate_with | ruby-1.9 ; haproxy-1.4 |
scales_from | |
scales_to | |
additional_storage | |
gear_size | small ; medium |
url | |
environment_variables | |
additional_gear_storage |
A.8. Deployments
Name | Valid Options |
---|---|
ref | |
artifact_url | |
hot_deploy | true ; false |
force_clean_build | true ; false |
deployments |
Appendix B. Revision History
Revision History | |||||||||
---|---|---|---|---|---|---|---|---|---|
Revision 2.1-2 | Thur 11 Dec 2014 | Bilhar Aulakh | |||||||
| |||||||||
Revision 2.1-1 | Wed 20 Aug 2014 | Bilhar Aulakh | |||||||
| |||||||||
Revision 2.1-0 | Fri May 16 2014 | Bilhar Aulakh | |||||||
| |||||||||
Revision 2.0-1 | Wed Feb 26 2014 | Bilhar Aulakh | |||||||
| |||||||||
Revision 2.0-0 | Mon Dec 9 2013 | Bilhar Aulakh | |||||||
|