# Google Mobile Data Plan Sharing API

## Motivation

The Google Mobile Data Plan Sharing API allows an operator to send information
about a user's (identified by [*user key*](https://developers.google.com/mobile-data-plan/v6_1/overview#establishing-cpid)) data
plan to GTAF. On this page, we outline the mechanism through which these updates
can be pushed to GTAF and thereby Google applications. The API currently allows
the DPA to send data plan status to GTAF to be consumed by a Google client.

## 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](https://isp.google.com)
for the ASN the DPA represents. See [Google Cloud OAuth 2.0 for Service
Accounts](https://developers.google.com/identity/protocols/OAuth2ServiceAccount)
for documentation on how to use OAuth with Google Cloud service accounts.

## Data Plan Updates

Currently the Google Mobile Data Plan Sharing API allows an operator to share
updates about a user's data plan:

- **Data Plan Status:** Captures current status of a user's data plan. For example, if a user is running out of data, an operator can push a data plan status update to GTAF which could then be used by GTAF to send a low balance [notification](https://developers.google.com/mobile-data-plan/v6_1/notifications) to the user.

## Identifying relevant users

The DPA needs a way to determine which users' data to send to GTAF. GTAF expects
to receive updates for the following users:

1. **Active CPIDs** : users with active CPIDs. Until the CPIDs that have been generated by the CPID endpoint are valid, the DPA SHOULD send updates about a user's data plan. If the `Accept-Language` header was set at the time of CPID creation, then the human readable strings in data plan status MUST be in that language.
2. **Registered MSISDNs** : to serve applications that have access to the MSISDN, GTAF will register the MSISDN with DPA as described in the [msisdn
   registration](https://developers.google.com/mobile-data-plan/v6_1/agent_api_specification#msisdn_register) section of the Data Plan Agent API. Once the MSISDN is registered, DPA SHOULD send updates about the user's data plan until the registration expires.

## API Description

### Sharing Data Plan Status

![](https://developers.google.com/static/mobile-data-plan/v6_1/images/get_data_plan_overview.svg)
**Figure 3. GTAF-DPA interaction when DPA shares data plan status with GTAF.**

Applications can receive data plan status information in two ways:

1. UE calls GTAF for data plan status information:
   1. The operator's DPA uses the Data Plan Sharing API to push a user's data plan status to GTAF. GTAF stores the plan status and its associated *user key*.
   2. Google application running on UE requests the data plan status information using a Google-internal API. The application includes the *user key* in its request.
   3. If the application can use cached data plan status then GTAF uses the *user key* to look up the user's data plan status. GTAF then returns this status to the UE.
2. GTAF pushes data plan status information to the UE:
   1. When relevant, data plan status received from the operator is directly pushed to the UE.

#### GTAF-DPA Interaction

The DPA uses an HTTPS POST to create and update an existing plan status entry
for a user to be used by a client. Currently GTAF supports *mobiledataplan* and
*youtube* as valid client identifiers. Here is an example request for an
operator with asn 12345 and *user key abcdef* sharing plan information with GTAF
for *youtube* client:

POST
https://mobiledataplansharing.googleapis.com/v1/operators/12345/clients/youtube/users/abcdef/planStatus

    {
      "plans": [{
        "planName": "ACME1",
        "planId": "1",
        "planCategory": "PREPAID",
        "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
        "planModules": [{
          "moduleName": "Giga Plan", // req.
          "trafficCategories": ["GENERIC"],
          "expirationTime": "2017-01-29T01:00:03.14159Z", // req.
          "overUsagePolicy": "BLOCKED",
          "maxRateKbps": "1500",
          "description": "1GB for a month", // req.
          "coarseBalanceLevel": "HIGH_QUOTA"
        }]
      }],
      "planInfoPerClient": {
        "youtube": {
          "rateLimitedStreaming": {
            "maxMediaRateKbps": 569
          }
        }
      },
      "languageCode": "en-US", // req.
      "expireTime": "2018-06-14T08:41:27-07:00", // req.
      "updateTime": "2018-06-07T07:41:22-07:00", // req.
      "title": "Prepaid Plan"
    }

> [!NOTE]
> **Note:** The full format of Google Mobile Data Plan Sharing API requests is described in the [reference section](https://developers.google.com/mobile-data-plan/v6_1/reference/rest/).

If the request is successful, GTAF will return HTTP response code 200 and the
pushed *planStatus* entry with a notifications entry if any notification was
sent to the user. If GTAF identifies a problem with the request, it will return
an HTTP status code in the range 400-499. If GTAF is unable to complete a
request due to a GTAF fault, GTAF will return an 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.

##### Plan Status Push for Default Client

GTAF continues to support the following call where the plan status is pushed by
the operator without specifying the client for which it can be used. In this
case, we assume that the plan status is intended for *mobiledataplan* client and
the operator intends to send a notification to the user. The request body is the
same for the per client use case and the default client use case.

POST
https://mobiledataplansharing.googleapis.com/v1/operators/12345/planStatuses?userKey=abcdef

### Internationalization

In order to support internationalization, the DPA must know the user's preferred
language even without a direct request from GTAF. To solve this issue the
request to the CPID endpoint MAY include an Accept-Language header. If the
header is included then human readable strings in updates that the DPA sends
using the MDP API must use the settings provided in the CPID request.