“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.


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 Data Mesh manages, optimizes, and integrates data among devices, systems, and applications. 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 fuel revenue growth, customer engagement, and business operations. The products, Diffusion® and Diffusion Cloud™, are available on-premise, in-the-cloud, or in a hybrid configuration, to fit the specific business and infrastructure requirements of the applications operating in today’s mobile obsessed, everything connected world. 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


Check out these other resources


Info Center

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


Quick Start Guide

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


Diffusion Cloud

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