PPW API Services

PPW customers may use their own app to access PPW resources through the PPW API Services.

In this document a PPW customer’s app is referred to as the “client app”.

The API Service uses OAuth2 client credentials grant type to authorize client apps. Therefore, the client app needs to be confidential — not exposed to the outside world.

Services

Each type of PPW “resource” is exposed as a “service” through this API. So, there will be a “Property” service for getting and updating information about properties; there will be a “Workorder” service for creating and updating work order information, and so on.

Each “service” will have a set of “actions” that allow the client app to access and update PPW resources connected to the respective “service”.

Data Format

Both API requests and responses will be in the JSON format. The client apps must set the content type in the header to application/json:

    curl -H 'Content-Type: application/json' \
         ... \
         https://ppw.web/svc/service/action

In all examples in this document, the API URL will be https://ppw.web/svc. PPW will provide the the actual API URL for the client app to use after successful registration.

Requests

The body of all requests to PPW API Services must be a JSON object.

All requests except the /auth/token must set the access token in the HTTP Authorization header in this format:

Authorization: Bearer ACCESS_TOKEN

Lastly, the requests must always be a HTTP POST.

Errors

The errors returned by the API will be in this format:

{
  "error": "ERROR_TYPE",
  "error_description": "Description of the error",
}

Flow

The client app must be registered with PPW before it can access the API Services. After successful registration, the client app will be provided client credentials which includes the client_id, the client_secret, and the permitted OAuth scopes. The client app can then use the client credentials to receive an access token from PPW. Finally, with the access token, the client app can access PPW API Services.

   (A)

   +------------------+                                +------------------+
   |                  |<---(1)-Register Client App----<|                  |
   |                  |                                |                  |
   |     PPW Web      |                                |   PPW Customer   |
   |                  |                                |                  |
   |                  |>---(2)-Client Credentials----->|                  |
   +------------------+                                +------------------+

   ----(*)----------------(*)----------------(*)----------------(*)--------

   (B)

   +------------------+                                +------------------+
   |                  |<---(1)-Client Credentials-----<|                  |
   |                  |                                |                  |
   |   PPW API Auth   |                                |    Client App    |
   |                  |                                |                  |
   |                  |>---(2)----Access Token-------->|                  |
   +------------------+                                +------------------+

   ----(*)----------------(*)----------------(*)----------------(*)--------

   (C)

   +------------------+                                +------------------+
   |                  |<---(1)----Access Token--------<|                  |
   |                  |                                |                  |
   | PPW API Services |                                |    Client App    |
   |                  |                                |                  |
   |                  |>---(2)------Response---------->|                  |
   +------------------+                                +------------------+