pxGrid Consumer

Consumer using pxGrid

pxGrid nodes connect to pxGrid Controller to perform control operations that facilitates communications between consumer nodes and provider nodes.

This guide discuss HTTP APIs use by consumer nodes.

pxGrid Control HTTP APIs

The HTTP APIs are all POST methods using JSON:

Request URL: https://<pxgrid-hostname>:8910/pxgrid/control/[method]
Request Method: POST
Content-Type: application/json
Accept: application/json
Authorization: Basic [nodeName]:[password if password-based authentication, otherwise empty string]

[nodeName] has a limit of 100 characters. It can contains alphanumerics (a-z, 0-9), dashes (-), underscores (_), and periods (.). It is case-insensitive.

Steps required before accessing pxGrid supported services:

	Name	Description
1	AccountActivate	Activate once at consumer startup
2	ServiceLookup	Get properties like URLs, topic... etc
3	AccessSecret	Get unique secret between 2 nodes

---

AccountActivate

https://<pxgrid-hostname>:8910/pxgrid/control/AccountActivate

Consumer must activate the account before proceeding to other APIs. The request can contain an optional description which is a string (max 50 characters. Alphanumerics, spaces, underscores(_), comma(,), dashes(-) and periods(.)).

The accountState in the response can be PENDING, DISABLED or ENABLED. ISE UI will display the new account in PENDING state for administrator to approve.

For PENDING state, the recommended wait time for retrying AccountActivate is at least 60 seconds. For DISABLED state, the recommended wait time for retrying AccountActivate is at least 5 minutes. Once ENABLED state is responded, the consumer can continue to use other APIs.

Request sample

{
    "description":"MyApp 1.0"
}

Response sample

{
    "accountState":"PENDING",
    "version":"2.0.0.2"
}

---

ServiceLookup

https://<pxgrid-hostname>:8910/pxgrid/control/ServiceLookup

ServiceLookup is used to find a service and its properties. The name of the service should be given in its corresponding documentation.

ServiceLookup returns a list of nodes providing the service. It contains a set of properties specific to the service. The properties can be URLs, topic names...etc. If service is not available, the ['services'] will be an empty array.

Request sample

{
    "name":"com.cisco.ise.pubsub"
}

Response sample

{
    "services":[
        {
            "name":"com.cisco.ise.pubsub",
            "nodeName":"ise-admin-pxgrid-002",
            "properties":
            {
                "wsUrl":"wss://pxgrid-002.cisco.com:8910/pxgrid/ise/pubsub"
            }
        }
    ]
}

---

AccessSecret

https://<pxgrid-hostname>:8910/pxgrid/control/AccessSecret

AccessSecret is a unique secret between a Consumer and Provider pair. The use of the secret is dictated by the implementation of the Provider. In the case of ISE, the secret is used as the password of HTTP Basic Auth.

Request sample

{
    "peerNodeName":"ise-admin-pxgrid-002"
}

Response sample

{
    "secret":"oWhgNC7oNpaulpJ6"
}

---

pxGrid high availability

Multiple pxGrid nodes can be enabled in ISE to provide high availability. All the pxGrid nodes provide the same functionality. A client should be configured with the IP addresses to all and make the call until one of the nodes works.

If none of the nodes work, it is recommended to retry at least 60 seconds later.

---

pxGrid account authentication

pxGrid account can be authenticated by password or certificate.

Password-based authentication requires AccountCreate first to obtain a password, and then perform AccountActivate using the credentials obtained.

Certificate-based authentication requires the use of a certificate that is trusted by ISE. Perform AccountActiviate using the client certificate, fill the Basic Auth header with username only.

Subsequence call will use Basic Auth header with "[username]:[password]" for password-based authentication, or "[username]:" for certificated-based authentication.

AccountCreate

https://<pxgrid-hostname>:8910/pxgrid/control/AccountCreate

For password-based authentication only. AccountCreate feature is disabled by default and has to be enabled via ISE UI.

This call does not require authentication.

It creates an account with nodeName and returns a generated password for subsequence calls. [nodeName] has a limit of 100 characters. It can contains alphanumerics (a-z, 0-9), dashes (-), underscores (_), and periods (.). It is case-insensitive.

If an account with the same nodeName already exist, an HTTP "409 Conflict" will be returned.

Note that HTTP Authorization header must not be used, otherwise pxGrid Controller will try to authenticate.

Request sample

{
    "nodeName":"MyName01"
}

Response sample

{
    "nodeName":"MyName01",
    "password":"P9nEaNX0cyA4DRBr"
}