Get started
Add dependencies/generate client
Working Group Two 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
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
}
2
3
4
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.
Summary
The steps needed to get started are:
Install dependencies or generate a client library from the public
.proto
files at github.com/working-group-two/wgtwoapisopen in new window.In Developer portalopen in new window: Create an organization, create a product, create a client, and add needed scopes.
Once this is done you can get an access token using OAuth 2.0 and use APIs accessing real data using that access token.