Get 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/wgtwoapisopen in new window.

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

gRPCurlopen in new window (like cURL, but for gRPC) is also available to use APIs from the command line.

Run hello world

1. Download our gRPC API definition

# Download the FileDescriptorSet for our APIs, which contains all our .proto files
curl -sL 'https://github.com/working-group-two/wgtwoapis/blob/master/image.bin?raw=true' -o wgtwo.bin

2. Install gRPCurl

brew install grpcurl

grpcurl() {
  docker run -v $(pwd)/wgtwo.bin:/wgtwo.bin fullstorydev/grpcurl "$@"
}

3. Make request

grpcurl -protoset wgtwo.bin \
  sandbox.api.wgtwo.com:443 \
  wgtwo.subscription.v1.SubscriptionEventService/StreamHandsetChangeEvents

4. See result

{
  "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

The example above uses no authorization and targets our sandboxed environment where you can experiment with the APIs, but not access any real (production) data.

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 OAuth 2.0 guide for how you can create a client and get your first access token.

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.wgtwo.com to api.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 wgtwo.bin \
  -H 'Authorization: Bearer UG5dO...' \ # Bearer (access token) added
  -d '
  {
    "stream_configuration": {
      "regular": {},
      "disable_explicit_ack": {}
    }
  }
  ' \
  api.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.

See configuring event streaming for details.

Error codes

All APIs go through a common API Gateway for authentication. That is, in addition to the responses from each service we have some common error responses.

Error description	REST status code	gRPC status code
Bad or expired credentials	401	UNAUTHENTICATED
Insufficient scopes	403	PERMISSION_DENIED
Ratelimit exceeded	429	RESOURCE_EXHAUSTED
Unimplemented	404	NOT_FOUND
Internal server error	500	INTERNAL

Note that for REST-ish APIs, the same status code of 404 will be included both if service is not implemented or a given entity is not found.

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/wgtwoapisopen in new window.

2. In Developer portalopen in new window: 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.