Getting Started with Mobile Data Plan Sharing API

Terminology

  • GTAF: Google Traffic Application Function. A Google service that implements the Data Plan Sharing API and interacts with DPAs on behalf of Google applications. Google applications query GTAF for the user's data plan information.
  • MSISDN: Mobile Station International Subscriber Directory Number, a number uniquely identifying a subscription in a mobile network. More generally known as phone number.
  • PGID Endpoint: A service implemented by mobile operators that generates planGroupId (PGID) identifiers that can be used to look up the subscriber's data plan group information. We describe the procedure for generating PGIDs below.
  • DPA: Data Plan Agent, a service implemented by mobile operators that shares user data plan information with GTAF through the Data Plan Sharing API.

API Description

At a high level, the API comprises two parts:

  1. Mechanism to establish and update an identifier called planGroupId (PGID).
  2. An API to share information about users' data plans.

Establishing planGroupId

GTAF uses planGroupId to identify a subscriber when communicating with the DPA. For applications that have access to the user's MSISDN, planGroupId may be the user's MSISDN. All other applications need to establish a planGroupId without discovering the user's MSISDN.

planGroupId Query

  1. A Google client uses a Google-internal API to retrieve the URL of the planGroupId endpoint. The carrier is identified using the client's public IP address.
  2. The Google client issues a HTTP GET request to the planGroupId endpoint.
  3. The planGroupId endpoints returns the planGroupId for the user (or an error code).

The format of the request is:

GET PGID_URL?app=YouTube

where YouTube is replaced by the name of the application requesting planGroupId. The response from the planGroupId endpoint should be JSON with the following schema:

{
    "cpid": "<planGroupId>",
    "ttlSeconds": integer
}

The returned planGroupId string must be URL-encoded, and must be valid for ttlSeconds seconds.

If an error occurs, a message of the following form should be returned:

{
    "error": "<error message>"
}

If a planGroupId request is received for a user who is roaming or who has not opted in to sharing data plan information with Google, the planGroupId endpoint must return HTTP status code 403.

Obtaining Data Plan Status

Here is the flow of data plan status information between the DPA, GTAF, and UE:

  1. The operator's DPA uses the Data Plan Sharing API to push a user's plan status (in the form of a PlanGroup) to GTAF. GTAF stores the PlanGroup and its associated planGroupId.
  2. UE requests the data plan status information using a Google-internal API. The client includes the planGroupId it received from the carrier's planGroupId endpoint.
  3. GTAF uses the planGroupId received from the UE and uses it to look up the user's data plan status (PlanGroup). GTAF then returns this status to the UE.

GTAF-DPA Interaction

The DPA uses the operators.createPlanGroup call to add new data plan status entries into GTAF, and operators.updatePlanGroup to update an existing plan group entry.

Here is an example createPlanGroup request for an operator with asn 12345:

POST https://mobiledataplansharing.googleapis.com/v1/operators/12345/planGroups

{
  "planGroupId": "abcdef",
  "planGroup": {
    "dataPlans": [
      {
        "planName": "ACME Red",
        "planId": "turbulent1",
        "expirationTime": "2020-02-03T04:05:06Z",
        "planModules": [
          {
            "byteBalance": {
              "quotaBytes": "1000000000",
              "remainingBytes": "9876543210"
            },
            "trafficCategories": [
              "GENERIC"
            ],
            "expirationTime": "2020-02-03T04:05:06Z"
          }
        ]
      }
    ],
    "responseStaleTime": "2018-03-04T05:06:07Z"
  }
}

Similarly, here is an example updatePlanGroup request for an operator with asn 12345 and planGroupId abcdef:

PUT https://mobiledataplansharing.googleapis.com/v1/operators/12345/planGroups/abcdef

{
  "dataPlans": [
    {
      "planName": "ACME Red",
      "planId": "turbulent1",
      "expirationTime": "2020-02-03T04:05:06Z",
      "planModules": [
        {
          "byteBalance": {
            "quotaBytes": "1000000000",
            "remainingBytes": "9876543210"
          },
          "trafficCategories": [
            "GENERIC"
          ],
          "expirationTime": "2020-02-03T04:05:06Z"
        }
      ]
    }
  ],
  "responseStaleTime": "2018-03-04T05:06:07Z"
}

If the request is successful, GTAF will return HTTP response code 200 and the pushed planGroup entry. If GTAF identifies a problem with the request, it will return a HTTP status code in the range 400-499. If GTAF is unable to complete a request due to a GTAF fault, GTAF will return a HTTP code in the range 500-599. Requests that receive a response in the 500-599 range are considered retryable and requests that receive a response in the 400-499 range are generally not retryable.

Authentication

All Data Plan Sharing API requests to GTAF must be authenticated using the Google Cloud OAuth2 server. The requests must be authenticated as a service account that has been whitelisted in the ISP Portal for the ASN the DPA represents. See Google Cloud OAuth 2.0 for Service Accounts for documentation on how to use OAuth with Google Cloud service accounts.

Monitoring API

Some use cases require GTAF to monitor the DPA and detect DPA failures. For those use cases, we have defined a monitoring API.

API Definition

The monitoring API should be available via HTTP GET request at the following URL:

DPA_URL/dpaStatus

The requests should use OAuth2 for authentication.

If the DPA and all of its backends are operating correctly, the DPA should respond to this query with HTTP status code 200 and a response in the following form (JSON):

{
    "status": "OPERATIONAL",
    "message": "<optional human-readable status description>"
}

If the DPA or any of its backends are not operating correctly, it should respond with HTTP status code 500 and a response in the following form (JSON):

{
    "status": "UNAVAILABLE",
    "message": "<optional human-readable error message>"
}

DPA Behavior

When a failure is detected, the DPA must return the "UNAVAILABLE" status for all dpaStatus queries. In addition, it must cease sending data plan information with long cache periods. It may cease sending responses with long cache periods in one of two ways:

  1. Start setting short cache expiry times.
  2. Cease sending data plan information entirely.

GTAF Behavior

GTAF will poll dpaStatus periodically. When it detects a DPA failure (based on the "UNAVAILABLE" response), it will clear its cache for the carrier.