Working with the Subscriptions API

The Subscriptions API is a powerful tool for being notified of changes in resources on the Triathlon API platform. Whilst the full functionality is currently in closed beta we have opened up subscriptions to the Rankings API via the app management portal.

The Subscriptions API implements webhooks to notify any subscribers of changes on the platform, which in the case of the Rankings API are either the rankings being run or published. Simply put, when a ranking is published a JSON payload is sent to a subscriber URL containing a message that indicates which ranking was run and any other relevant meta data. For example when the female ITU World Series Rankings are published the following message would be sent.

{  
   "subscription":"ranking.publish",
   "payload":{  
      "id":16,
      "category":"Elite Women",
      "last_updated":"2016-09-08 17:49:23",
      "type":"World Triathlon Series",
      "region_id":null
   }
}

Based on this message the recipient can make changes on their own systems. For example making a subsequent request for the full ranking information such that the user always has the latest ranking information available. As the notification happens in real-time it saves the user from continuously checking the rankings to know if they have the latest ranking information as they will be notified of any changes as they occur.

Whilst currently only the Rankings API is supported with the rankings.publish and rankings.run methods we will include all data sources in due course. By incorporating these other subscriptions example use cases include:

• A press release could be sent on the publishing of a new article using article.publish
• A National Federation could add/update information in a local database once profile information has been updated on Triathlon.org using athlete.store or athlete.update
• A race organizer could be notified of entries as they occur and any changes to entries using entry.store, entry.update or entry.destroy

The beauty of webhooks is in their flexibility and they can be used to trigger a huge variety of existing services such as the Zapier service. For the remainder of this article we will detail a process of using the Subscription API to be notified via text message (using Twilio) whenever the female World Triathlon Series rankings are published. Clearly this approach may be applied to more practical use-cases such as updating an internal database when rankings are published thus ensuring that the most up-to-date information is always available.

Creating a Subscription

To create a subscription log into the API management portal and choose Register a Subscription and you will be displayed the following form: (it is also possible to create subscriptions via the API directly).

The form contains options for customizing the notification sent:

• Name: A name to identify the subscription
• URL: The webhook URL to send the generated messages
• Token: An optional secret token which is included in all outgoing requests such that you can be assured that the message was sent from the Triathlon API
• Email Notifications: Whether you wish to receive an email notification for any failed webhook notifications (note that the Subscriptions API uses an exponential back-off style retry policy such that several delivery attempts are made before a failure would occur)
• Subscriptions: The subscription(s) to which we wish to subscribe

In our case we will generate a URL from the Zapier service which will receive our webhook request. Once registered and signed in to Zapier we will create a new Zap with our Trigger App as a Catch Hook from the Zapier Webhooks app which will give us a custom URL to use to add to the Subscription API form (you may leave all other Zapier options as their defaults). Once we have the URL to post to we submit the Subscription API form using a descriptive name and subscribing to the ranking.publish notification. Now whenever any ranking is published a webhook will be sent to our new Zapier app.

Using the Webhook as a Trigger

🚧

Zapier has over 500 integrations with other services that you may substitute for the example Twilio application demonstrated

Currently we are receiving all ranking.publish notifications whereas we are only interested in the women's rankings of the ITU World Triathlon Series. By using the Rankings Listing method of the Triathlon API or by consulting this table we can see that the ranking_id that we are interested in is 16. In order to restrict when notifications trigger our SMS message we will apply a Filter step in Zapier to only continue if the Payload ID is equal to 16 (see the payload object in the same message above).

Finally, we will implement the Twilio integration in Zapier to actually send the message (you would need to be a Twilio subscriber and authenticate the service in Zapier). We will use the Send SMS action and customise the message body so that the name of the ranking is displayed in the resulting SMS.

Note that it would also be possible to add a further step to retrieve the full rankings using the `ranking_id` and then for example save the results in a Google Sheet integration.

Now when the women's ITU World Triathlon Series rankings are published we receive the following message via SMS.

You can discuss this article or using the Subscription API on our Slack channel.