Quick start

Request an Access Token

APPA uses an OAuth2 provider for authentication. There are several grant types offered by the OAuth2 protocol. Your OAuth2 grant type will depend on your application type. Our preferred grant type for web applications is the “authorization code” grant type. To start this authentication flow, link the user to our authorization endpoint. An example of an authorization URL (that you could use as an href on an anchor tag, for example) follows. Please note, this example reads as if your app is hosted at “myapp.com”:

GET https://account.publicpower.org/o/authorize/

Example request:

GET /o/authorize/?response_type=code&scope=ert.write+ert.read&redirect_uri=https://myapp.com/login/&client_id=12345 HTTP/1.1
Host: account.publicpower.org

Query Parameters

• response_type – “code”

• scope – “ert.write ert.read” means your application is requesting to read and write to the API on behalf of the authenticating user

• redirect_uri – The URL where you would like the APPA provider to send the authorization code after a successful login

• client_id – The OAuth2 client id you were given when you first requested to integrate with eRT API.

The user will enter their user name and password into a form on account.publicpower.org. After they successfully authenticate, the user’s browser will be redirected to the redirect_uri you specified above with a code parameter value set.

GET https://myapp.com/login/

Example request:

GET /login/?code=thanksforthecode HTTP/1.1
Host: myapp.com

You’re responsible for writing an OAuth2 consumer. In this case, the consumer would listen for requests coming into /login/ with a code parameter. The consumer would pass this code to the APPA token endpoint. An example of that interaction follows:

POST https://account.publicpower.org/o/token/

Example request:

POST /o/token/ HTTP/1.1
Host: account.publicpower.org

grant_type=authorization_code&
code=thanksforthecode&
redirect_uri=https://myapp.com/login/&
client_id=12345&
client_secret=xxyyzz

Form Parameters

• grant_type – “authorization_code”

• code – The code you received from account.publicpower.org (via the user’s browser’s request)

• redirect_uri – The same redirect_uri you specified in the authorization request

• client_id – The OAuth2 client id you were given when you first requested to integrate with eRT API.

• client_secret – The OAuth2 client secret you were given along with the client_id.

Example response:

HTTP/1.1 200 OK

 {
     "scope": "ert.write ert.read",
     "expires_in": 36000,
     "access_token": "PDSDH8okZYBZsFSnXLOLsRupkD22MJ",
     "refresh_token": "YWQkSgr5DgNs2g1KatEQDyMbA6JnV",
     "token_type": "Bearer"
 }

Note that the access_token in the response will be used in the Authorization: HTTP header for your interactions with the eRT API. In the following examples replace “yourAccessToken” with the access_token from the response.

Create Event

Creating an Event is the first step in creating an Outage. A successful POST request will return the Event data encoded in JSON.

Your POST request will be made to https://reliability.api.publicpower.org/v1/events/ and should have two headers:

Header	Value
Authorization	Bearer yourAccessToken
Content-Type	application/vnd.api+json

Your POST request should include a body formatted as follows:

{
  "data": {
    "attributes": {
      "name": "607 de Souza Rd, Esperanza, CA, 43958"
    },
    "type": "Event"
  }
}

A successful POST request will receive a response similar to the following. The “id” value will be needed when Creating an Outage.

{
  "data": {
    "type": "Event",
    "id": "1",
    "attributes": {
      ...
    }
  }
}

Creating an Outage

Once you have the id value for your event, you can create an Outage. A successful POST request will return the Outage data encoded in JSON.

Your POST request will be made to https://reliability.api.publicpower.org/v1/outages/ and should have two headers:

Header	Value
Authorization	Bearer yourAccessToken
Content-Type	application/vnd.api+json

Your POST request should include a body formatted as follows:

{
    "data": {
        "attributes": {
            "address": "607 de Souza Rd, Esperanza, CA, 43958",
            "startDatetime": "2015-10-06T22:02:04Z",
            "totalCustomers": 100,
            "totalCustomersImpacted": 30
        },
        "relationships": {
            "cause": {
                "data": {
                    "id": "{{cause id}}",
                    "type": "Cause"
                }
            },
            "circuit": {
                "data": {
                    "id": "{{circuit id}}",
                    "type": "Circuit"
                }
            },
            "event": {
                "data": {
                    "id": "{{event id}}",
                    "type": "Event"
                }
            },
            "substation": {
                "data": {
                    "id": "{{substation id}}",
                    "type": "Substation"
                }
            },
            "utility": {
                "data": {
                    "id": "{{utility id}}",
                    "type": "Utility"
                }
            }
        },
        "type": "Outage"
    }
}

A successful POST request will receive a response similar to the following:

{
  "data": {
    "type": "Outage",
    "id": "1",
    "attributes": {
      ...
    }
  }
}