Getting Started

Add Dependencies/Generate Client

APIs are available using .proto files and gRPC to autogenerate client libraries for most popular languages.

.proto files are available at github.com/working-group-two/wgtwoapis.

Quickstart guides for popular languages such as Go, C++, Java, Python, and C# are available at gRPC.io.

gRPCurl (like cURL, but for gRPC) is also available to use APIs from the command line.

Run Hello world

1. Install gRPCurl

brew install grpcurl

grpcurl() {
  docker run fullstorydev/grpcurl "$@"
}

2. Make a Request

grpcurl \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.subscription.v1.SubscriptionEventService/StreamHandsetChangeEvents

3. See Results

{
  "metadata": {
    "timestamp": "2021-09-30T14:27:55.468Z",
    "identifier": {
      "subscriptionIdentifier": {
        "value": "ce78..."
      }
    },
    "ackInfo": {
      "value": "Ch5..."
    }
  },
  "handsetChangeEvent": {
    "previous": {
      "imeiSv": {
        "imei": "867...",
        "softwareVersion": "64"
      }
    },
    "current": {
      "imeiSv": {
        "imei": "867...",
        "softwareVersion": "65"
      }
    },
    "imsi": {
      "value": "Rn..."
    }
  }
}

Move Out of Sandboxed Environment

To make onboarding easy, all our sample doc omits the Authorization header.

Authentication is optional for our sandbox environment, but must be added before going to production.

You will need to create an OAuth 2.0 client to access our production environment.

Get a Correctly Scoped Client From Developer Portal

Follow the Authentication guide for how you can create a client and get your first access token.

This guide also shows how to include the access token in your requests.

For this API, you will need to the scope subscription.handset_details:read.

If you are unfamiliar with OAuth 2.0 see How OAuth 2.0 works.

Change URL To Target Production

Change sandbox.api.shamrock.wgtwo.com to api.{region}.wgtwo.com.

See Environments reference for more.

Get an Access Token

See Get client access token.

This API requires that you use the client credentials flow, so the access token will authenticate your product.

Use API With Authorization (Access Token)

grpcurl \
  --protoset mobility.binpb \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d '
  {
    "stream_configuration": {
      "regular": {},
      "disable_explicit_ack": {}
    }
  }
  ' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.subscription.v1.SubscriptionEventService/StreamHandsetChangeEvents
About stream_configuration

For testing purposes, we include the config:

"stream_configuration": {
  "regular": {},              Reading position will not be stored in the server and load is not spread between your clients
  "disable_explicit_ack": {}  Let events be automatically acked
}

By default, load will automatically be spread between all connections using the same OAuth 2.0 client and you will need to reply with a ack once your service has handled the message. This is also what we would recommend for real production usage.

Summary

The steps needed to get started are:

  1. Install dependencies or generate a client library from the public .proto files at github.com/working-group-two/wgtwoapis.

  2. In Developer portal: Create an organization, create a product, create a client, and add needed scopes.

  3. Once this is done you can get an access token using OAuth 2.0 and use APIs accessing real data using that access token.