Red Hat Summit Red Hat SummitApoyoConsolaDesarrolladoresIniciar una pruebaContacto

Este contenido no está disponible en el idioma seleccionado.

REST API Guide

OpenShift Enterprise 2

Reference documentation for OpenShift Enterprise Representational State Transfer Application Programming Interface (REST API)

Red Hat OpenShift Documentation Team

Abstract

The OpenShift Enterprise REST API Guide is a reference to the REST API of OpenShift Enterprise. This guide explains each API resource, and where applicable, describes the parameters associated with that resource, with the resulting output example shown in JSON syntax. This provides the basis for developers to develop applications to interact with OpenShift Enterprise.

Chapter 1. Introduction to OpenShift Enterprise
Copiar enlace

OpenShift Enterprise by Red Hat is a Platform as a Service (PaaS) that provides developers and IT organizations with an auto-scaling, cloud application platform for deploying new applications on secure, scalable resources with minimal configuration and management overhead. OpenShift Enterprise supports a wide selection of programming languages and frameworks, such as Java, Ruby, and PHP. Integrated developer tools, such as Eclipse integration, JBoss Developer Studio, and Jenkins, support the application life cycle.
Built on Red Hat Enterprise Linux, OpenShift Enterprise provides a secure and scalable multi-tenant operating system for today's enterprise-class applications while providing integrated application runtimes and libraries.
OpenShift Enterprise brings the OpenShift PaaS platform to customer data centers, enabling organizations to implement a private PaaS that meets security, privacy, compliance, and governance requirements.

1.1. Introduction to OpenShift API
Copiar enlace

OpenShift provides a Representational State Transfer (REST) Application Programming Interface (API). OpenShift applications access the API using the standard Hypertext Transfer Protocol (HTTP). The OpenShift REST API is structured as a resource, and provides links to all children and any related resources.

Note

The legacy API has been removed, and is no longer supported. All customers are advised to use the current OpenShift REST API.

1.2. Introduction to Representational State Transfer (REST)
Copiar enlace

Representational State Transfer (REST) is a design architecture for networked applications or systems. In the REST design architecture a client progresses through an application by selecting links, also known as state transitions. Each link selected by the client returns a representation of the selected resource. Also, with each resource representation the client application transfers state, and results in a usable web page being transferred and rendered.
In the REST design architecture, a resource is created for every service that an application provides, with each resource identified by a URL. A client can reference the resource using the URL. The returned representation of the resource is further linked to more information, allowing the client to drill down as far as necessary to get more detailed information. The client can access and perform operations on available resources with standard HTTP methods, such as GET, POST, PUT, and DELETE.

Chapter 2. General API Information
Copiar enlace

2.1. Authentication
Copiar enlace

The OpenShift API supports multiple authentication mechanisms, including Basic Authentication and authorization tokens.
Basic 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}" }
Copy to Clipboard Toggle word wrap
Python
import base64
base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
request.add_header("Authorization", "Basic %s" % base64string)
Copy to Clipboard Toggle word wrap
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
Copy to Clipboard Toggle word wrap
Authorization Tokens

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.

When you have an authorization token, you can substitute it in place of your login credentials, as shown in the following format: 
$ curl https://openshift.redhat.com/broker/rest/user -H "Authorization: Bearer token_id"curl https://openshift.redhat.com/broker/rest/user -H "Authorization: Bearer token_id"curl https://openshift.redhat.com/broker/rest/user -H "Authorization: Bearer token_id"
Copy to Clipboard Toggle word wrap

Example 2.1. cURL Command with Authorization Token

The following example shows a REST call to delete an application using an authorization token for authentication instead of a user name and password. 
curl -X DELETE https://openshift.redhat.com/broker/rest/application/5406971c5973ca2a7f0000c6 -H "Authorization: Bearer 14fc97947174a911c3d1154aa846197cbc18ad550d7ad1cdd58aab105e65783a"
Copy to Clipboard Toggle word wrap

2.2. Version
Copiar enlace

Every OpenShift REST API call returns the current API version, and other versions that are supported. The following example shows how to use the cURL command to return the API version. 
$ curl "https://openshift.redhat.com/broker/rest/api"
Copy to Clipboard Toggle word wrap
The following examples show the response for this command in both XML and JSON syntax.
XML Response

<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>
Copy to Clipboard Toggle word wrap

JSON Response

{
   "supported_api_versions": [
        1.0,
        1.1,
        1.2,
        1.3,
        1.4
        1.5
        1.6
    ],
    "version": "1.6"
}
Copy to Clipboard Toggle word wrap

If a specific API version is required, the client must include the HTTP header with the response request. The following examples show response requests in both XML and JSON syntax.
XML Clients

Accept: application/xml; version=1.5
Copy to Clipboard Toggle word wrap

JSON Clients

Accept: application/json; version=1.5
Copy to Clipboard Toggle word wrap

If the version requested by the client is not supported, the server responds with the HTTP status code 406, as shown in the following examples in XML and JSON syntax.
XML Response for Unsupported Version

<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>
Copy to Clipboard Toggle word wrap

JSON Response for Unsupported Version

{
    "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"
}
Copy to Clipboard Toggle word wrap

2.4. Response Information
Copiar enlace

The following table describes information contained in each API response.
Expand
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
Copiar enlace

The following table describes the parameters contained in each message from the API response. The API can return zero or more messages.
Expand
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

Messages that return severity=result contain information that is passed to the user. Examples include database user names and passwords.

2.6. Response Type
Copiar enlace

Although OpenShift supports both XML and JSON response formats, the default server response is the JSON syntax. Include the following HTTP header to receive the response in XML: 
Accept: application/xml
Copy to Clipboard Toggle word wrap
Using Ruby

headers = {"Accept" => "application/xml"}
Copy to Clipboard Toggle word wrap

Using Python

request.add_header("Accept", "application/xml")
Copy to Clipboard Toggle word wrap

Using cURL

curl "https://openshift.redhat.com/broker/rest/api" -H "Accept: application/xml"
Copy to Clipboard Toggle word wrap

2.7. Status Codes
Copiar enlace

The OpenShift REST API attempts to return standard HTTP status codes. The more common status codes are shown in the following table along with a brief description of each.
Expand
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
Copiar enlace

Description

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 and URL Structure

Expand
Method URL Structure
GET /broker/rest/api

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/api
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

Chapter 4. User Information
Copiar enlace

This chapter provides information on API resources that allow a client to manage OpenShift user account information.
The following table describes each parameter associated with a user account.
Expand
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.
The following table further describes each available capability for the user.
Expand
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
Copiar enlace

Description

Provides resource links to view user information, and manage user SSH keys.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/user

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/user --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

4.2. Parent and Child Accounts
Copiar enlace

Parent accounts that have the subaccounts capability enabled can contain child user accounts. See Chapter 4, User Information for more information on all user account parameters and capabilities.

4.2.1. Delete Child Account
Copiar enlace

Description

Delete the specified child user account, if one exists.

Note

Parent accounts cannot be deleted. Therefore, the API returns an error message if you attempt to delete a parent account.
Method and URL Structure

Expand
Method Resource URL
DELETE /broker/rest/user

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/user -d --user child_user:password
Copy to Clipboard Toggle word wrap

JSON Response

No content is returned from a successful DELETE operation.

Chapter 5. SSH Keys
Copiar enlace

This chapter provides information on API resources that allow a client to view and manage SSH keys.
The following table describes each parameter associated with SSH keys.
Expand
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
Copiar enlace

Description

Add an SSH key to the specified user account.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/user/keys

Request Parameters

Expand
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

See Section A.1, “SSH Keys” for more information about the valid options applicable to these request parameters.
Request

{
  "name": "mysshkey",
  "type": "ssh-rsa",
  "content": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDBJHobjmzxy8cv9A1xw9X5TlnQd0bW/19FwOC0c6jPNu9ZbtWQcAE0xfODl7ZqVPPU2qAFOh4rbL3gL2UzTyA+NwERyDrH7tMXAoXPT2L6sqExl0xxuEvb/lXUfLquMq+BMOFxxqCEg8X7GavHN72FMUHwweNybE7C82So+OFSWqFoctiWMNdNsKW4lvBd/jkIudGdRdK+/PzV75TW1LcpfsBrFOJZbd5WzDJEPNdMqOH68YDExD82VtzeJm0HEavhMY9HtxIDEmjIhtfedzCGZLe+6OxReuatw6M+n1sFxT9liprZ6NIANvbnYZKGT50hYfnIi/hZOTCvqYNS97O3"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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==
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

5.2. List User SSH Keys
Copiar enlace

Description

Get a list of SSH keys for an OpenShift user.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/user/keys

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/user/keys --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

5.3. Get SSH Key Information
Copiar enlace

Description

View the contents of an SSH key.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/user/keys/:name

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/user/keys/mysshkey --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

5.4. Update SSH Key
Copiar enlace

Description

Update the contents of an existing SSH key.

Method and URL Structure

Expand
Method Resource URL
PUT /broker/rest/user/keys/:name

Request Parameters

Expand
Name Description Required Default
type Type of key Yes
content The key portion of an rsa key (excluding ssh-rsa and comment) Yes

See Section A.1, “SSH Keys” for more information about the valid options applicable to these request parameters.
Request

{
  "type": "ssh-rsa",
  "content": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDBJHobjmzxy8cv9A1xw9X5TlnQd0bW/19FwOC0c6jPNu9ZbtWQcAE0xfODl7ZqVPPU2qAFOh4rbL3gL2UzTyA+NwERyDrH7tMXAoXPT2L6sqExl0xxuEvb/lXUfLquMq+BMOFxxqCEg8X7GavHN72FMUHwweNybE7C82So+OFSWqFoctiWMNdNsKW4lvBd/jkIudGdRdK+/PzV75TW1LcpfsBrFOJZbd5WzDJEPNdMqOH68YDExD82VtzeJm0HEavhMY9HtxIDEmjIhtfedzCGZLe+6OxReuatw6M+n1sFxT9liprZ6NIANvbnYZKGT50hYfnIi/hZOTCvqYNS97O3"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

Note

It is recommended to URL encode the key contents because it might contain non alphanumeric characters.
JSON Response

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"
}
Copy to Clipboard Toggle word wrap

5.5. Delete SSH Key
Copiar enlace

Description

Delete an SSH key from a user account.

Method and URL Structure

Expand
Method Resource URL
DELETE /broker/rest/user/keys/:name

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/user/keys/mysshkey --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

{
  "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"
}
Copy to Clipboard Toggle word wrap

The API returns an error message if the SSH key to be deleted is not found. 
{
    "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"
}
Copy to Clipboard Toggle word wrap

Chapter 6. Authorizations
Copiar enlace

This chapter provides information on API resources to add, view, and manage authorization tokens. An authorization token is a secret value that is used to automatically log in to an OpenShift Enterprise account without entering login information each time. A token is also used to grant another user full or partial access to an account, determined by the scope of the token.
Authorization tokens are easily managed and offer better security because there is no need to repeatedly supply login credentials. For example, if a password is ever compromised, the password must be reset. If a secret authorization token is compromised, that token can be revoked and another one created.
The following table describes each parameter associated with an OpenShift authorization token.
Expand
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.
The following table describes the available scope options that determine the type of access a user is granted with an authorization.
Expand
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
Copiar enlace

Description

Add an authorization to the specified user account.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/user/authorizations

Request Parameters

Expand
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.

See Section A.2, “Authorizations” for more information about the valid options applicable to these request parameters.
Request

{
  "scope": "userinfo",
  "note": "This is my UPDATED note to myself",
  "expires_in": -1,
  "reuse": false
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

6.2. List Authorizations
Copiar enlace

Description

List all authorizations for the specified user account and provide the client with additional resource links to manage existing authorizations.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/user/authorizations

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/user/authorizations --user user@example.com:password"
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

6.3. Get Authorization Information
Copiar enlace

Description

Get information about the specified authorization.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/user/authorizations/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/user/authorizations/52141fa2e499b2229e00009b --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

6.4. Update an Authorization
Copiar enlace

Description

Update an existing authorization for the specified user account. However, currently this operation only supports updating the note parameter of an existing authorization.

Method and URL Structure

Expand
Method URL Structure
PUT /broker/rest/user/authorizations/:id

Request Parameters

Expand
Name Description Required Default
note Reminder description of authorization. Yes

See Section A.2, “Authorizations” for more information about the valid options applicable to these request parameters.
cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

6.5. Delete an Authorization
Copiar enlace

Description

Delete the specified authorization.

Method and URL Structure

Expand
Method URL Structure
DELETE /broker/rest/user/authorizations/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/user/authorizations/52141fa2e499b2229e00009b --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

Chapter 7. Domains
Copiar enlace

This chapter provides information on API resources to add, update, and manage OpenShift user domains. A domain must be created before OpenShift applications can be created. Domain names on OpenShift are non-strict, meaning there is no preceding period, and form part of the application name. Therefore, the syntax for the application name is ApplicationName-DomainName.rhcloud.com.
The following table describes each parameter associated with an OpenShift domain.
Expand
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
Copiar enlace

Description

Create a new domain for an OpenShift user account. Note that a domain is required to create applications on OpenShift Enterprise.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/domains

Request Parameters

Expand
Name Description Required Default
name Name of domain Yes
allowed_gear_sizes List of gear sizes that can be created on this domain No

See Section A.3, “Domains” for more information about the valid options applicable to these request parameters.
Request

{
  "name": "mydomain",
  "allowed_gear_sizes": "small"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

7.2. List Domains
Copiar enlace

Description

Get a list of all domains accessible to the user, regardless of ownership.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/domains

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/domains --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

7.3. List Domains by Owner
Copiar enlace

Description

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 and URL Structure

Expand
Method URL Structure
GET /broker/rest/domains

Request Parameters

Expand
Name Description Required Default
owner List domains owned by specified user, or @self for current user Yes

See Section A.3, “Domains” for more information about the valid options applicable to these request parameters.
Request

{
  "owner": "@self"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/domains --user user@example.com:password --data-urlencode owner=@self
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

7.4. Get Domain Information
Copiar enlace

Description

Get information about an existing domain.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/domains/:name

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/domains/mydomain --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

7.5. Update Domain
Copiar enlace

Description

Update an existing domain.

Method and URL Structure

Expand
Method URL Structure
PUT /broker/rest/domains/:name

Request Parameters

Expand
Name Description Required Default
name Name of domain Yes
allowed_gear_sizes Array of zero or more gear sizes allowed on this domain No

See Section A.3, “Domains” for more information about the valid options applicable to these request parameters.
Request

{
  "name": "mydomainX",
  "allowed_gear_sizes": "small"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

7.6. Remove Self from a Domain
Copiar enlace

Description

Remove yourself from a domain.

Method and URL Structure

Expand
Method URL Structure
DELETE /broker/rest/domain/:name/members/self

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/domain/mydomain/members/self --user user@example.com:password
Copy to Clipboard Toggle word wrap

7.7. Delete a Domain
Copiar enlace

Description

Delete an existing domain.

Note

The API exits with an error message if there are applications within the domain to be deleted. Therefore, all applications must be deleted before deleting a domain. Setting the force parameter to true automatically deletes all applications under that domain and then deletes the domain.

Warning

Deleting a domain with the force parameter set to true deletes all applications created within that domain. This operation cannot be reversed.
Method and URL Structure

Expand
Method URL Structure
DELETE /broker/rest/domains/:name

Request Parameters

Expand
Name Description Required Default
force Force delete domain No false

See Section A.3, “Domains” for more information about the valid options applicable to these request parameters.
cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/domains/mydomain --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

In this case, the user must delete all applications that exist under the domain or set the force parameter to true to automatically delete the applications as part of the domain delete process.

Chapter 8. Teams
Copiar enlace

This chapter provides information on API resources to create and manage OpenShift Enterprise teams. A team comprises a group of developers for the purpose of access control. Team members are added to a domain similar to how users are added.
The following table describes each parameter associated with an OpenShift Enterprise team.
Expand
Name Description
name Name of the team
id Unique identifier of the team

8.1. Create Team
Copiar enlace

Description

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.

When creating a team, the following guidelines apply:
  • 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 and URL Structure

Expand
Method URL Structure
POST /broker/rest/teams

Request Parameters

Expand
Name Description Required Default
name [a] Name of the team Yes
[a] Must be minimum of 2 characters, and maximum of 250 characters in length

See Section A.4, “Teams” for more information on request parameters for this resource.
Request

{
  "name": "myteam",
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/teams --user user@example.com:password --data-urlencode name=myteam
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

8.2. List Teams
Copiar enlace

Description

Get a list of teams that you are a member of.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/teams

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/teams --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

8.3. List Teams by Owner
Copiar enlace

Description

Get a list of teams owned by a particular user, specified with the owner parameter.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/teams

Request Parameters

Expand
Name Description Required Default
owner List teams owned by specified user, or @self for current user Yes

See Section A.4, “Teams” for more information on request parameters for this resource.
Request

{
  "owner": "@self"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/teams --user user@example.com:password --data-urlencode owner=@self
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

8.4. Search Teams by Name
Copiar enlace

Description

Search teams with the specified string.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/teams

Request Parameters

Expand
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

See Section A.4, “Teams” for more information on request parameters for this resource.
Request

{
  "search": "engineering",
  "global": true
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/teams --user user@example.com:password --data-urlencode search=engineering --data-urlencode global=true
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

8.5. Get Team Information
Copiar enlace

Description

Get information about an existing team.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/team/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

8.6. Remove Self from a Team
Copiar enlace

Description

Remove yourself from a team owned by another user.

Method and URL Structure

Expand
Method URL Structure
DELETE /broker/rest/team/:id/members/self

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/members/self --user user@example.com:password
Copy to Clipboard Toggle word wrap

8.7. Delete Team
Copiar enlace

Description

Delete an existing team.

Method and URL Structure

Expand
Method URL Structure
DELETE /broker/rest/team/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae --user user@example.com:password
Copy to Clipboard Toggle word wrap

Chapter 9. Members
Copiar enlace

This chapter provides information on API resources to create and manage OpenShift Enterprise members. A member is a developer or a team with access to a domain.
The following table describes each parameter associated with members.
Expand
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
Copiar enlace

Description

Get a list of members that belong to the specified domain.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/domains/:name/members

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/domains/mydomain/members --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

9.2. Add or Remove Domain Members
Copiar enlace

Description

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

Note that the number of teams allowed in a domain is determined by the MAX_TEAMS_PER_RESOURCE parameter.
Method and URL Structure

Expand
Method URL Structure
PATCH /broker/rest/domains/:name/members

Request Parameters

Expand
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   

See Section A.5, “Members” for more information about the valid options applicable to these request parameters.
Request

{
  "role": "view",
  "login": "member@example.com"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

9.3. List Members of an Application
Copiar enlace

Description

Get a list of members that belong to the specified application.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/application/:id/members

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/521bf818656c67309c000001/members --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

9.4. Add Team Member
Copiar enlace

Description

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 and URL Structure

Expand
Method URL Structure
POST /broker/rest/team/:id/members

Request Parameters

Expand
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

See Section A.5, “Members” for more information about the valid options applicable to these request parameters.
Request

{
  "role": "view",
  "login": "member@example.com"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

9.5. List Members of a Team
Copiar enlace

Description

Get a list of members that belong to the specified team.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/team/:id/members

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/members --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

9.6. Add or Remove Team Members
Copiar enlace

Description

Add one or more members to a team, or remove them from a team.

Method and URL Structure

Expand
Method URL Structure
PATCH /broker/rest/team/:id/members

Request Parameters

Expand
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

See Section A.5, “Members” for more information about the valid options applicable to these request parameters.
Request

{
  "role": "view",
  "login": "member@example.com"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

9.7. Get Member Information
Copiar enlace

Description

Get information about an existing team member.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/team/:id/member/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003 --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

9.8. Update Team Member
Copiar enlace

Description

Update the role of a team member.

Method and URL Structure

Expand
Method URL Structure
PUT /broker/rest/team/:id/member/:id

See Section A.5, “Members” for more information about the valid options applicable to these request parameters.
Request Parameters

Expand
Name Description Required Default
role Type of role user has on the team Yes

Request

{
  "role": "view",
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X PUT https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003 --user user@example.com:password --data-urlencode role=view
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

9.9. Delete Team Member
Copiar enlace

Description

Delete a team member.

Method and URL Structure

Expand
Method URL Structure
DELETE /broker/rest/team/:id/member/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/team/5333d8b2a9429d1c3e0000ae/member/533369f861b322dfc1000003--user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

In this case, the user must delete all applications that exist under the domain or set the force parameter to true to automatically delete the applications as part of the domain delete process.

Chapter 10. Quickstarts
Copiar enlace

This chapter provides information on API resources for OpenShift quickstart applications. Quickstarts provide quick access to new technology with code and libraries preconfigured, but you are responsible for updating the core libraries for security updates.
The following table describes each parameter associated with an OpenShift quickstart application.
Expand
Name Description
id Unique identifier of the quickstart.
search The search term to use for the quickstart.

10.1. List Quickstarts
Copiar enlace

Description

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 and URL Structure

Expand
Method URL Structure
GET /api/v1/quickstarts/promoted.json

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://www.openshift.com/api/v1/quickstarts/promoted.json --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
            }
        },
    ]
}
Copy to Clipboard Toggle word wrap

10.2. Show Quickstart
Copiar enlace

Description

Get information about the specified quickstart. The client does not have to retrieve the quickstarts list and scan for a known ID.

Method and URL Structure

Expand
Method URL Structure
GET /api/v1/quickstarts/:id

Request Parameters

Expand
Name Description Required Default
id Unique identifier of the quickstart Yes

cURL Command Example

$ curl -X GET https://www.openshift.com/api/v1/quickstarts/12724 --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
            }
        }
    ]
}
Copy to Clipboard Toggle word wrap

10.3. Search Quickstarts
Copiar enlace

Description

Search for a quickstart using a search term.

Method and URL Structure

Expand
Method URL Structure
GET /api/v1/quickstarts.json?search=search_term

Request Parameters

Expand
Name Description Required Default
search Search term to use for the quickstart. Yes

cURL Command Example

$ curl -X GET https://www.openshift.com/api/v1/quickstarts.json?search=wordpress --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
            }
        }
    ]
}
Copy to Clipboard Toggle word wrap

Chapter 11. Applications
Copiar enlace

This chapter provides information on API resources that allow a client to create and manage OpenShift applications. OpenShift supports a number of application frameworks such as PHP, JBoss, and Ruby.
The following table describes each parameter associated with an OpenShift application.
Expand
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
Copiar enlace

Description

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 and URL Structure

Expand
Method URL Structure
GET /broker/rest/application/:id/dns_resolvable

Request Parameters

Not applicable

cURL Command Example

$ curl GET https://openshift.redhat.com/broker/rest/applications/534253991015616165707776/dns_resolvable --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.2. Create an Application
Copiar enlace

Description

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 and URL Structure

Expand
Method URL Structure
POST /broker/rest/domain/:domain_name/applications

Request Parameters

Expand
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

Valid cartridge options may be different based on your OpenShift Enterprise deployment.

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "name": "myapp",
  "cartridges": "ruby-2.0",
  "scale": "true",
  "gear_size": "small",
  "initial_git_url": ""
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

In the previous cURL command example, the 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
Copy to Clipboard Toggle word wrap
JSON Response

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"
}
Copy to Clipboard Toggle word wrap

Note

An application may not be immediately available after it is created. Therefore, ensure the application DNS resolves correctly before executing other REST API calls to that application.

11.3. List Applications by Owner
Copiar enlace

Description

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 and URL Structure

Expand
Method URL Structure
GET /broker/rest/applications

Request Parameters

Expand
Name Description Required Default
owner List applications owned by specified user, or @self for current user Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "owner": "@self"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/applications --user user@example.com:password --data-urlencode owner=@self
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.4. List Applications for a User
Copiar enlace

Description

List all applications for the specified user.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/applications

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/applications --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.5. List Applications for a Domain
Copiar enlace

Description

List all applications for the specified domain.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/domain/:name/applications

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/domain/mydomain/applications --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.6. List Applications and Cartridges
Copiar enlace

Description

Get a list of all applications for the specified domain including all cartridges.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/domain/:name/applications?include=cartridges

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/domains/mydomain/applications?include=cartridges --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.7. Get Application Information
Copiar enlace

Description

Get information about an existing application.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/application/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/52131ae36cec0e0d5f00012b
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.8. Get Application and Cartridge Information
Copiar enlace

Description

Get information about an existing application and its embedded cartridges.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/application/:id?include=cartridges

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/5213190e2587c8817a000121?include=cartridges --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.9. Update an Application
Copiar enlace

Description

Update an application.

Method and URL Structure

Expand
Method Resource URL
PUT /broker/rest/application/:id

Request Parameters

Expand
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

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "auto_deploy": true,
  "deployment_type": "git"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.10. Enable High Availability (HA) on Application
Copiar enlace

Description

Enable high availability (HA) feature on an application.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "make-ha"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/527ade9d7f9c48d37100000a/events --user user@example.com:password --data-urlencode event=make-ha
Copy to Clipboard Toggle word wrap

11.11. Disable High Availability (HA) on Application
Copiar enlace

Description

Disable high availability (HA) feature on an application.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "disable-ha"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/527ade9d7f9c48d37100000a/events --user user@example.com:password --data-urlencode event=disable-ha
Copy to Clipboard Toggle word wrap

11.12. Start Application
Copiar enlace

Description

Start an application that is not running.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "start"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com:password --data-urlencode event=start
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.13. Stop Application
Copiar enlace

Description

Stop a running application.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "stop"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=stop
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.14. Force Stop Application
Copiar enlace

Description

Force a running application to stop.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "force-stop"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com:password --data-urlencode event=force-stop
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.15. Restart Application
Copiar enlace

Description

Restart a running application.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "restart"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com:password --data-urlencode event=restart
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.16. Scale Up Application
Copiar enlace

Description

Scale up an application that was created with the scaling function enabled.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "scale-up"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=scale-up
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

The API returns an error message if a user has reached the maximum number of gears allowed for their account, as shown in the sample response output below. 
{
    "status": "unprocessable_entity",
    "messages": [
        {
            "field": null,
            "text": "user@example.com has already reached the gear limit of 3",
            "severity": "error",
            "exit_code": 104
        }
    ]
}
Copy to Clipboard Toggle word wrap

11.17. Scale Down Application
Copiar enlace

Description

Scale down an application that was created with the scaling function enabled.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "scale-down"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=scale-down
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

The API returns an error message if an application cannot be scaled down any further, as shown in the sample response output below. 
{
    "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
        }
    ]
}
Copy to Clipboard Toggle word wrap

11.18. Tidy Application Framework
Copiar enlace

Description

Tidy the application framework.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "tidy"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=tidy
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.19. Reload Application
Copiar enlace

Description

Reload an application.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "reload"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=reload
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.20. Trigger Thread Dump
Copiar enlace

Description

Trigger application thread dump.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.6, “Applications” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "thread-dump"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/events --user user@example.com --data-urlencode event=thread-dump
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

11.21. Delete Application
Copiar enlace

Description

Delete an OpenShift application.

Method and URL Structure

Expand
Method Resource URL
DELETE /broker/rest/application/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/application/534253991015616165707776 -user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

{
  "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"
}
Copy to Clipboard Toggle word wrap

Chapter 12. Application Aliases and SSL Certificates
Copiar enlace

This chapter provides information on API resources that allow a client to manage application aliases and SSL certificates for OpenShift applications.
The following table describes each parameter associated with an OpenShift application with aliases and SSL certificates added.
Expand
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
Copiar enlace

Description

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 and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/aliases

Request Parameters

Expand
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

Request

{
  "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"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases --user user@example.com --data-urlencode id=myappalias
Copy to Clipboard Toggle word wrap
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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

12.2. List Application Aliases
Copiar enlace

Description

List all aliases and SSL certificates associated with the specified application.

Note

A GET request to an application also returns a list of associated aliases for that particular application . See Section 11.7, “Get Application Information” for more information.
Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/application/:id/aliases

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

12.3. Get Application Alias Information
Copiar enlace

Description

Get information about the specified application alias.

Note

A GET request to an application also returns a list of associated aliases for that particular application . See Section 11.7, “Get Application Information” for more information.
Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/application/:id/aliases/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases/myappalias --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

12.4. Update Application Alias
Copiar enlace

Description

Update an existing application alias with a new SSL certificate or remove an existing certificate.

Method and URL Structure

Expand
Method Resource URL
PUT /broker/rest/application/:id/aliases/:id

Request Parameters

Expand
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

Request

{
  "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"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

12.5. Delete Application Alias
Copiar enlace

Description

Remove an alias from an application.

Method and URL Structure

Expand
Method Resource URL
DELETE /broker/rest/application/:id/aliases/:id

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/application/534253991015616165707776/aliases/myappalias --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

{
  "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"
}
Copy to Clipboard Toggle word wrap

Chapter 13. Cartridges
Copiar enlace

This chapter provides information on API resources that allow a client to manage OpenShift cartridges. Cartridges are the components of an OpenShift application, and include databases, build systems, and management capabilities. Adding a cartridge to an application provides the desired capability without having administer or update the included feature. There are two types of cartridges available with OpenShift: standalone and embedded.
Standalone 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.

The following table describes each parameter associated with both standalone and embedded cartridges.
Expand
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

The 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

Embedded cartridges provide extended functionality to OpenShift applications. Examples include MySQL, PostgreSQL, and Jenkins Client.

The following table describes each parameter associated with only embedded cartridges.
Expand
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
Copiar enlace

Description

Get a list of all available OpenShift cartridges.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/cartridges

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/cartridges --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

13.2. Embedded Cartridges
Copiar enlace

Embedded cartridges are added to an OpenShift application to extend functionality. For example, a MySQL cartridge provides database support for an application.

13.2.1. Add Embedded Cartridge
Copiar enlace

Description

Add an embedded cartridge to an application.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/cartridges

Request Parameters

Expand
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

See Section A.7, “Cartridges” for more information about the valid options applicable to these request parameters.
Request

{
  "name": "mysql-5.5",
  "colocate_with": "ruby-2.0",
  "gear_size": "small"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
    },
Copy to Clipboard Toggle word wrap

13.2.2. List Embedded Cartridges
Copiar enlace

Description

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 of all embedded cartridges can also be retrieved with the LIST_APPLICATIONS resource. See Section 11.6, “List Applications and Cartridges” for more information.
Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/application/:id/cartridges

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridges --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

13.2.3. Get Cartridge Information
Copiar enlace

Description

Get information for the specified cartridge using the cartridge name or unique ID.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/application/:id/cartridge/:name

Request Parameters

Not applicable

cURL Command Example

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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

13.2.4. Update Cartridge Configuration
Copiar enlace

Description

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

Contact your system administrator for more information.
Method and URL Structure

Expand
Method Resource URL
PUT /broker/rest/application/:id/cartridge/:name

Request Parameters

Expand
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

See Section A.7, “Cartridges” for more information about the valid options applicable to these request parameters.
Request

{
  "additional_gear_storage": 10
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

The API returns an error message if the user account does not allow additional gear storage. 
{
    "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"
}
Copy to Clipboard Toggle word wrap

13.2.5. Get Cartridge Status
Copiar enlace

Description

Retrieve the status_messages string as an array for the specified cartridge in an application.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/domain/:name/applications/:name/cartridge/:name

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/domain/mydomain/applications/myapp/cartridge/mysql-5.5?include=status_messages --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
            }
        ],
Copy to Clipboard Toggle word wrap

13.2.6. Start Cartridge
Copiar enlace

Description

Start an application's embedded cartridge that is not running.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/cartridge/:name/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.7, “Cartridges” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "start"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5/events --user user@example.com --data-urlencode event=start
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

13.2.7. Stop Cartridge
Copiar enlace

Description

Stop an application's embedded cartridge that is running.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/cartridge/:name/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.7, “Cartridges” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "stop"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5/events --user user@example.com --data-urlencode event=stop
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

13.2.8. Restart Cartridge
Copiar enlace

Description

Restart a running embedded cartridge.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/cartridge/:name/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.7, “Cartridges” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "restart"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5/events --user user@example.com --data-urlencode event=restart
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

13.2.9. Reload Cartridge
Copiar enlace

Description

Reload the embedded cartridge configuration if it has been modified.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/cartridge/:name/events

Request Parameters

Expand
Name Description Required Default
event Event Yes

See Section A.7, “Cartridges” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "reload"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5/events --user user@example.com --data-urlencode event=reload
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

13.2.10. Delete Cartridge
Copiar enlace

Description

Delete an embedded cartridge from an application.

Method and URL Structure

Expand
Method Resource URL
DELETE /broker/rest/application/:id/cartridge/:name

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/application/534253991015616165707776/cartridge/mysql-5.5 --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

{
  "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"
}
Copy to Clipboard Toggle word wrap

Chapter 14. Deployment
Copiar enlace

The deployment API resource contains information about each application deployment.
The following table describes each parameter associated with an application deployment.
Expand
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
Copiar enlace

Description

Get a list of deployments for the specified application.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/application/:id/deployments

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/5255b678b78bba421d000008/deployments --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

14.2. Deploy an Application
Copiar enlace

Description

Deploy the specified application.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/deployments

Request Parameters

Expand
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

See Section A.8, “Deployments” for more information about the valid options applicable to these request parameters.
Request

{
  "ref": "master",
  "hot_deploy": false,
  "force_clean_build": false
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

14.3. Activate a Deployment of an Application
Copiar enlace

Description

Activate a particular deployment for the specified application.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/events

Request Parameters

Expand
Name Description Required Default
event Event Yes
deployment_id Deployment ID to activate the application Yes

See Section A.8, “Deployments” for more information about the valid options applicable to these request parameters.
Request

{
  "event": "activate",
  "deployment_id": "f36f59c0"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

14.4. Update an Application Deployment
Copiar enlace

Description

Update a deployment of an application. Note that special permissions are required to update deployments.

Method and URL Structure

Expand
Method Resource URL
POST /broker/rest/application/:id/deployments

Request Parameters

Expand
Name Description Required Default
deployments An array of deployments Yes

See Section A.8, “Deployments” for more information about the valid options applicable to these request parameters.
cURL Command Example

$ curl -X POST https://openshift.redhat.com/broker/rest/application/5255b678b78bba421d000008/deployments --user user@example.com:password
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

Chapter 15. Environment Variables
Copiar enlace

This chapter provides information on API resources that allow a client to add and manage user defined application environment variables. The environment variables can be set when an application is created, when a cartridge is added to an application, or they can be added to an existing application. User defined environment variables are persistent and replicated through all application gears, including new gears added in scaling events.
The following table describes each parameter associated with OpenShift environment variables.
Expand
Name Description
name Name of the environment variable
value Value of the environment variable

15.1. Add Environment Variable
Copiar enlace

Description

Add an environment variable to the specified application.

Method and URL Structure

Expand
Method URL Structure
POST /broker/rest/application/:id/environment-variables

Request Parameters

Expand
Name Description Required Default
name Name of environment variable No
value Value of environment variable No

Request

{
  "name": "MY_ENV_VAR",
  "value": "myvalue"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ 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
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

Environment variables can also be added when an application is created, or when a cartridge is added to an application.
See Section 11.2, “Create an Application” for more information on adding environment variables when creating an application.
See Section 13.2.1, “Add Embedded Cartridge” for more information on adding environment variables when adding a cartridge to an application.

15.2. List Environment Variables
Copiar enlace

Description

Get a list of all environment variables associated with the specified application.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/application/:id/environment-variables

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variables --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

15.3. Get Environment Variable Information
Copiar enlace

Description

Get information about the specified environment variable.

Method and URL Structure

Expand
Method Resource URL
GET /broker/rest/application/:id/environment-variable/ENV_VAR_NAME

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variable/MY_ENV_VAR --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

15.4. Update Environment Variable
Copiar enlace

Description

Update the value of an existing environment variable.

Method and URL Structure

Expand
Method URL Structure
PUT /broker/rest/application/:id/environment-variable/ENV_VAR_NAME

Request Parameters

Expand
Name Description Required Default
value Value of environment variable Yes

Request

{
  "value": "mynewvalue"
}
Copy to Clipboard Toggle word wrap

cURL Command Example

$ curl -X PUT https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variable/MY_ENV_VAR --user user@example.com --data-urlencode value=mynewvalue
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

15.5. Delete Environment Variable
Copiar enlace

Description

Delete an existing environment variable.

Method and URL Structure

Expand
Method Resource URL
DELETE /broker/rest/application/:id/environment-variable/ENV_VAR_NAME

Request Parameters

Not applicable

cURL Command Example

$ curl -X DELETE https://openshift.redhat.com/broker/rest/application/534253991015616165707776/environment-variable/MY_ENV_VAR --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

{
    "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"
}
Copy to Clipboard Toggle word wrap

Chapter 16. Gear Groups
Copiar enlace

Gear groups are of the same size and share scaling limit in terms of maximum number of gears. A gear group is automatically created when a scaled application is created, or when a cartridge is added to a scaled application. For an application that is not scalable, only one gear group gets created. All cartridges in a gear group scale together.

16.1. Get Application Gear Groups
Copiar enlace

Description

Get a list of gear groups where each group represents a list of gears that share scaling and storage policies.

Note

Section 13.2.2, “List Embedded Cartridges” provides information on how to view scaling and storage policies for scaled cartridges.
Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/application/:id/gear_groups

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/application/5213190e2587c8817a000121/gear_groups --user user@example.com
Copy to Clipboard Toggle word wrap

JSON Response

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"
Copy to Clipboard Toggle word wrap

16.2. Get Application Gear Endpoints
Copiar enlace

Description

Get API endpoints for individual application gears.

Method and URL Structure

Expand
Method URL Structure
GET /broker/rest/applications/:id/gear_groups

Request Parameters

Not applicable

cURL Command Example

$ curl -X GET https://openshift.redhat.com/broker/rest/applications/5213190e2587c8817a000121/gear_groups --user user@myemail.com --data-urlencode include=endpoints
Copy to Clipboard Toggle word wrap

Request

{
  "include": "endpoints"
}
Copy to Clipboard Toggle word wrap

JSON Response

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"
}
Copy to Clipboard Toggle word wrap

Appendix A. Valid Options for API Resources
Copiar enlace

A.1. SSH Keys
Copiar enlace

Expand
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

See Also:

A.2. Authorizations
Copiar enlace

Expand
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

See Also:

A.3. Domains
Copiar enlace

Expand
Name Valid Options
name
allowed_gear_sizes small; medium; large; c9
owner User input; @self
force  

See Also:

A.4. Teams
Copiar enlace

Expand
name Valid Options
name [a]
owner @self
search [b]
global true; false
[a] Must be minimum of 2 characters, and maximum of 250 characters in length
[b] Must be minimum of 2 characters in length if specified

See Also:

A.5. Members
Copiar enlace

Expand
Name Valid Options
role view; edit; admin; none [a]
id
login
type user; team [b]
[a] Note that only the view option is valid when adding members to a team.
[b] Note that only the user option is valid when adding members to a team.

See Also:

A.6. Applications
Copiar enlace

Expand
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
Copiar enlace

Expand
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

See Also:

A.8. Deployments
Copiar enlace

Expand
Name Valid Options
ref
artifact_url
hot_deploy true; false
force_clean_build true; false
deployments  

See Also:

Appendix B. Revision History
Copiar enlace

Revision History
Revision 2.1-2Thur 11 Dec 2014Bilhar Aulakh
OpenShift Enterprise 2.2.2 release.
Updated title of Section 11.10, “Enable High Availability (HA) on Application” and added Section 11.11, “Disable High Availability (HA) on Application” to disable HA.
Revision 2.1-1Wed 20 Aug 2014Bilhar Aulakh
Updated Section 11.2, “Create an Application” and Section 16.1, “Get Application Gear Groups” with new region parameter.
Updated Ruby cartridge information to version 2.0 in various topics.
Revision 2.1-0Fri May 16 2014Bilhar Aulakh
OpenShift Enterprise 2.1 release.
Updated Section 11.2, “Create an Application” with information about domain being automatically created.
Added API resources for teams and team members.
Added API resource: Section 11.3, “List Applications by Owner”.
Added API resource: Section 7.6, “Remove Self from a Domain”.
Added API resource: Section 14.4, “Update an Application Deployment”.
Revision 2.0-1Wed Feb 26 2014Bilhar Aulakh
BZ 1051636: Added note about application availability to Section 11.2, “Create an Application”.
BZ 1048758: Fixed URL path in REST calls for environment variables.
Revision 2.0-0Mon Dec 9 2013Bilhar Aulakh
OpenShift Enterprise 2.0 release.
Added information about deploying applications with artifact_url.
Added API resource for gear endpoints.
Added API resources to manage environment variables.
Added API resource to tidy application framework.
Added API resource to trigger thread dump.
Updated all screen samples and references for API v1.6.

Legal Notice

Copyright © 2025 Red Hat

OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).

Modified versions must remove all Red Hat trademarks.

Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.

Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation’s permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.

Volver arriba
Red Hat logoGithubredditYoutubeTwitter

Aprender

Pruebe, compre y venda

Comunidades

Acerca de la documentación de Red Hat

Ayudamos a los usuarios de Red Hat a innovar y alcanzar sus objetivos con nuestros productos y servicios con contenido en el que pueden confiar. Explore nuestras recientes actualizaciones.

Hacer que el código abierto sea más inclusivo

Red Hat se compromete a reemplazar el lenguaje problemático en nuestro código, documentación y propiedades web. Para más detalles, consulte el Blog de Red Hat.

Acerca de Red Hat

Ofrecemos soluciones reforzadas que facilitan a las empresas trabajar en plataformas y entornos, desde el centro de datos central hasta el perímetro de la red.

Theme

© 2025 Red Hat