Skip to content

pxGrid Provider

Jump to bottom
Alan Lei edited this page Sep 14, 2017 · 10 revisions

Provider using pxGrid

Still under contruction...

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

This guide discuss REST APIs use by provider nodes.

REST APIs

The REST 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]

Steps required before accessing pxGrid supported services:

Name Description
1 AccountActivation Activate once at provider startup
2 ServiceRegister/ServiceReregister/ServiceUnregister
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 '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"
}

ServiceRegister

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

ServiceRegister is used to register a service and its properties.

ServiceRegister returns id and a reregisterTimeMillis. id is used for subsequence ServiceReregister and ServiceUnregister commands. reregisterTimeMillis is the time in milliseconds that this service must re-register.

Request sample
{
    "name":"com.cisco.ise.pubsub",
    "nodeName":"ise-admin-pxgrid-002",
    "properties":
    {
        "wsUrl":"wss://pxgrid-002.cisco.com:8910/pxgrid/ise/pubsub"
    }
}
Response sample
{
    "id":"123",
    "reregisterTimeMillis":"60000"
}

ServiceReregister

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

ServiceReregister is used to signify that the service is still active

ServiceReregister returns nothing

Request sample
{
    "id":"123"
}
Response sample
{
}

ServiceUnregister

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

ServiceUnregister is used to un-register the service

Request sample
{
    "id":"123"
}
Response sample
{
}

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 pasword 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 REST 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 REST 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 REST call does not require authentication.

It creates an account for the node and returns a generated password for subsequence REST calls.

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

Request sample
{
    "nodeName":"MyName01"
}
Response sample
{
    "nodeName":"MyName01",
    "password":"P9nEaNX0cyA4DRBr"
}
Clone this wiki locally