< Back to Tutorials

“Hello World” With Diffusion Cloud’s REST API

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

View all Tutorials