“Hello World” With Diffusion’s REST API

Ben Henley - September 16, 2020

This tutorial walks you through a very brief “Hello World” project that will show you how to send and receive data from a Diffusion Cloud service using the REST API (formerly known as the Service API).

You can watch a video version of this tutorial on YouTube.

In this project, we will add some data to Diffusion Cloud where it will be stored as a topic. Then we will fetch the data.

The REST API uses simple HTTPS calls, so you can call it from any programming language. It’s completely stateless, which makes it good for devices and frameworks that can’t maintain a persistent connection. Unlike the Diffusion SDKs, the REST API does not stream real-time data – when retrieving data, it fetches a snapshot of the current state.

Requirements

Obtain an access token

In your Cloud service dashboard, go to Adapters > Service API.

At the top of the page you will see your Client ID and Client Secret.

Use them to replace CLIENT_ID and CLIENT_SECRET in this curl command, then run it:

curl \
    --request POST \
    --url https://login.ad.diffusion.cloud/oauth/token \
    --header 'content-type: application/json' \
    --data '{ "client_id": "CLIENT_ID", "client_secret": "CLIENT_SECRET", "audience": "https://api.diffusion.cloud", "grant_type": "client_credentials" }' > token.json

The output is saved to a token.json file.

View the file to see your access token. You might want to use jq to view a nicely formatted version of the file. Install jq and then run:

jq . token.json

This is an example of the file contents:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlJqUXpPVFUzUkRNMk9USTFSakUyUmtFNU5UaEJOemN4TVVaRk9URXlORE5DTkRsRVFVWkVOdyJ9.eyJpc3MiOiJodHRwczovL2xvZ2luLmFkLmRpZmZ1c2lvbi5jbG91ZCJGTThDcUxPbzAxVmQ4c0hJWTJwMXpJZGhGSUZpTlZ6dUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZW9a7fg99uLmNsb3VkIiwiaWF0IjoxNjAwMjYyOTcyLCJleHAiOjE2MDAzNDkzNzIsImF6cCI6IkZNOENxTE9vMDFWZDhzSElZMnAxeklkaEZJRmlOVnp1IiwiZ3R5IjoiY2xzIn0.OoXToMW5RdES5Fe_QCTvUIP4HI3heJmiJ7rnoKHh_moQK40pazrfB6_VAIIa6L_ljkrbgBo0yVCwbbzVzAYPyiMAQ91N3knnH2ztmhBem0ItnUwX-ip8D8zPR-eyg1tsrqJTTRIYnK9OHIYpaICTgJlY8Q8IIQ6RUuVmRyqpdxUPwAT2DE9zhayGj--GPBDHdG5Z2ocV0G7vDtqexVE0RQYq_RvAT_YqNga-bj8q-RcF4zzsDnwnK-za5WlO-CG3MCIEECQbFCu8HiaPxtSIbIGoFkfALjzWlQcYOc4wRQKthbt4hc2vKXPTvDA8TSZxBTnkw",
  "expires_in": 86400,
  "token_type": "Bearer"
}

The access token itself is the long string. You use it as a Bearer token to authenticate HTTP requests. Note that it expires in 86400 seconds, which is 24 hours.

Save your access token as an environment variable for convenience:

export ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlJqUXpPVFUzUkRNMk9USTFSakUyUmtFNU5UaEJOemN4TVVaRk9URXlORE5DTkRsRVFVWkVOdyJ9.eyJpc3MiOiJodHRwczovL2xvZ2luLmFkLmRpZmZ1c2lvbi5jbG91ZCJGTThDcUxPbzAxVmQ4c0hJWTJwMXpJZGhGSUZpTlZ6dUBjbGllbnRzIiwiYXVkIjoiaHR0cHM6Ly9hcGkuZW9a7fg99uLmNsb3VkIiwiaWF0IjoxNjAwMjYyOTcyLCJleHAiOjE2MDAzNDkzNzIsImF6cCI6IkZNOENxTE9vMDFWZDhzSElZMnAxeklkaEZJRmlOVnp1IiwiZ3R5IjoiY2xzIn0.OoXToMW5RdES5Fe_QCTvUIP4HI3heJmiJ7rnoKHh_moQK40pazrfB6_VAIIa6L_ljkrbgBo0yVCwbbzVzAYPyiMAQ91N3knnH2ztmhBem0ItnUwX-ip8D8zPR-eyg1tsrqJTTRIYnK9OHIYpaICTgJlY8Q8IIQ6RUuVmRyqpdxUPwAT2DE9zhayGj--GPBDHdG5Z2ocV0G7vDtqexVE0RQYq_RvAT_YqNga-bj8q-RcF4zzsDnwnK-za5WlO-CG3MCIEECQbFCu8HiaPxtSIbIGoFkfALjzWlQcYOc4wRQKthbt4hc2vKXPTvDA8TSZxBTnkw"

Share data

To share data using Diffusion Cloud, you store it in a topic.

First, create an empty topic:

curl \
--request POST \
--url https://api.diffusion.cloud/topics/add \
--header "authorization: Bearer $ACCESS_TOKEN" \
--header 'content type: application/json' \
- d '{"path":"MyTopic"}'

Note the use of double quotes for the authorization header, so that the shell replaces $ACCESS_TOKEN with the full string that you set as a variable.

The path of the topic is specified in the JSON request body.

Now you can set the value of the topic:

curl \
--request POST \
--url https://api.diffusion.cloud/topics/set \
--header "authorization: Bearer $ACCESS_TOKEN" \
--header 'content-type: application/json' \
-d '{"path":"MyTopic", "value":"Hello World"}'

Go to your Diffusion Cloud service and log in to the console using the Console link at right, using the admin credentials you created when you first set up the service.

In the Topics tab you will see your topic.

Click Subscribe to topic and descendants and you will go to the Topic Subscriptions page, where you can see values of topics you have subscribed to.

Now submit a new request with a different value, and notice how the value updates immediately.

Fetch data

You can fetch the current data in your topic like this:

curl \
--request GET \
--url https://api.diffusion.cloud/topics/fetch\?path\=MyTopic \
--header "authorization: Bearer $ACCESS_TOKEN"; echo

What next?

Instead of using curl, you can call the REST API from any programming language that has an HTTP stack.

Look at the API documentation for how to remove a topic. You can use the REST API to set topic properties which enable features like automatic topic removal after a certain time.

If you want to use more advanced Diffusion features like efficient real-time data streaming, request-response messaging and time series, you will need to use one of the full SDKs.

SDK downloads and documentation

A Hello World tutorial with the JavaScript SDK


The Diffusion® Intelligent Event-Data Platform makes it easy to consume, enrich and deliver event-data in real-time across all network conditions. Push Technology pioneered and is the sole provider of real-time delta data streaming™ technology that powers mission-critical business applications worldwide. Leading brands use Push Technology to bring innovative products to market faster by reducing the software development efforts using the low-code features. The Diffusion® Intelligent Event-Data Platform is available on-premise, in-the-cloud, or in a hybrid configuration. Learn how Push Technology can reduce infrastructure costs, and increase speed, efficiency, and reliability, of your web, mobile, and IoT application.

Learn More: View Blog Posts and Developer Resources

Share:

Check out these other resources

Info

Info Center

Case Studies, White Papers, and Tech Talk notes relating to Diffusion and the customers benefiting from using it.

Info

Quick Start Guide

Step-by-step guide to getting started fast with Diffusion or Diffusion Cloud.

Info

Diffusion Cloud

Get the facts and the details about our Diffusion Cloud platform.