The BlackBerry Proxy acts as an enterprise access point for a number of services that can be used by application servers. For example, the Push Channel back-end interface can be accessed through this enterprise access point.

The legacy Good Proxy also acts as an access point, for the same services.

For resilience and capacity, an enterprise can deploy multiple access point servers, in clusters. Any server can be used as an access point for any service, so an application server (App Server) can benefit from the increased resilience and capacity of clustered deployment.

See also: BlackBerry Dynamics enterprise server documentation on the help and manuals website for background on server clustering in a BlackBerry Dynamics deployment.

Services

The following application programming interface (API) is offered to App Servers by the BlackBerry Dynamics platform to enable the benefits of clustering. getGPServers Get a list of servers that can be used to access services.

Addressing Service Requests

The access point for services in this API is a BlackBerry Dynamics server that forms the part of the BlackBerry Dynamics proxy infrastructure that is installed on the enterprise network.

Requests can be addressed to an access point by specifying its server address and port number directly. Requests could also be addressed indirectly, through a load balancer, virtual IP address, or other component of the enterprise network. The server address would be provided by the enterprise's IT or network administration. By default, a BlackBerry Dynamics enterprise access point will accept:

Plain HTTP connections on port 17080.
Secure HTTP connections on port 17433.

It is recommended that production App Servers connect over a secure connection, and that plain HTTP is only used during the development phase. See under Certificates for Service Requests, below, for details of the electronic certificates that could be required when addressing service requests on a secure connection. Any certificates that are required should be obtained from the enterprise IT or network administration.

Note that the main purpose of this API is actually to provide a list of server addresses, which means that a "bootstrap" approach should be taken. The address of a single access point server could be provided when the App Server is installed. The App Server can then send a service request to that server, which will in turn provide a list of all the access point servers in the deployment for use going forwards. See under the getGPServers Service, below, for details of the API.

Certificates for Service Requests

Service requests in this API can be sent over a secure HTTP connection, the establishment of which requires the usual presentation and trusting of electronic certificates.

When service requests are addressed to an enterprise access point over a secure connection, its certificate must be trusted by the App Server. The certificate presented will be one of the following:

Certificate signed by the Certificate Authority (CA) generated for the management console during installation.
Certificate signed by an Enterprise CA.
Certificate signed by a trusted third party CA.

The first of these is the default, applying unless action has been taken to install a different root CA on the management console.

If the certificate is signed by a management console or Enterprise CA, then a corresponding CA certificate must also be installed on the App Server as a trusted CA. If no such certificate is installed, the App Server will not be able to establish a secure HTTP connection to the access point, and hence won't be able to send service requests.

getGPServers Service

Call this service to obtain a list of access point servers. The list is specific to a particular App Server, depending on clustering and affinity configuration in the enterprise management console.

Service requests can be addressed to any of the access point servers on the list. In the case that the list contains more than one server, the recommended selection algorithm is as follows.

For each priority value in the list, starting with the highest:
Select a server that has that priority, at random.
Attempt to connect to the server.
If connection succeeds, use that server.
If connection fails, try another server at the same priority, at random.
If there are no more untried servers at that priority, try the servers at the next lower priority.

App Servers should poll the service at least daily, to update their lists of access point servers.

Method

GET

Path

/getGPServers

Protocol

HTTP/1.1

Host

Enterprise access point address and port number

See under Addressing Service Requests, above, for details. This is a standard HTTP field.

Parameters

server= configuredAddress

Mandatory parameter specifying the address of the App Server that is calling the service. The value must be as it appears in the enterprise management console user interface.

port= portNumber

Parameter specifying the port number of the App Server that is calling the service.

If a port number is set for the App Server in the enterprise management console, then this parameter is mandatory. The value of this parameter must then be the same as the port number that is set in the console.

Response

The service returns a standard HTTP/1.1 response. The status will be 200, if the service received the request. A Content-Length header will be included. No other response headers will be included.

Response body

The response body will contain a list of servers in a JavaScript Object Notation (JSON) string.

The returned string will evaluate to an object with a single attribute. The attribute will be an array of objects, with each object containing the details for one access point server. Each access point server object will contain two attributes:

"server": A string containing the address of the server.
"priority": A numeric representation of the priority of the server. Lower numbers represent higher priority, with 1 representing the highest.

If the server address specified in the request parameter is not configured, then the array will be empty.

Examples

List of Servers

The following is an example of a request to the service.

GET /getGPServers?server=app-server.corp.example.com&port=8100 HTTP/1.1

Host: gp1.corp.example.com:17433

The following is an example response.

HTTP/1.1 200 OK
Content-Length: 265
 
{
    "gpServers": [
        {
            "server": "gp1.corp.example.com",
            "priority": 1
        },
        {
            "server": "gp2.corp.example.com",
            "priority": 1
        },
        {
            "server": "gpbackup.corp.example.com",
            "priority": 2
        }
    ]
}

In this case, the details for three access point servers have been returned. Two of the servers have primary priority, the other has secondary priority.

No Servers

The following is an example of a request to the service.

GET /getGPServers?server=hub&port=8100 HTTP/1.1

Host: gp1.corp.example.com:17433

The following is an example response.

HTTP/1.1 200 OK
Content-Length: 35
 
{
    "gpServers": [
    ]
}

In this case, the supplied server name in the request was not configured and the response therefore includes an empty array.