Fetching topics

Single topic

You can fetch the value of a single topic with the REST API.

curl --include                                              \
     --request POST                                         \
     --url https://api.diffusion.cloud/topics/fetch         \
     --header 'authorization: Bearer <TOKEN>'               \
     --header 'content-type: application/json'              \
     -d '{"path":"my-topic", "type":"json"}'

Multiple topics

You can fetch the values of multiple topics using a topic selector. For example, this will fetch the values of my-topic and any descendant topics (such as my-topic/a or my-topic/a/b) as an array:

curl --include                                              \
     --request POST                                         \
     --url https://api.diffusion.cloud/topics/fetch         \
     --header 'authorization: Bearer <TOKEN>'               \
     --header 'content-type: application/json'              \
     -d '{"selector":"*my-topic//", "type":"json"}'

If you have lots of topics, this could return a large number of results; hence, responses are paged. The default size is 10 results per page.

For example, if the topic selector above, matches 100 topics, the response only includes values for the first 10. This is the beginning of the response body:

{
"has_more":true,
"results":
    [
        {"path":"my-topic","type":"json","value":{"foo":"bar"}},
        {"path":"my-topic/a","type":"json","value":{"foo":"bar"}},
        ...
    ]
}

The has_more value of true tells you that there are more values.

You can request the next set of values using the after parameter. For example, the last value you had received was for the topic my-topic/a/b/c/d/e. You could send this request to get the next 10 values:

curl --include                                                                          \
     --request POST                                                                     \
     --url https://api.diffusion.cloud/topics/fetch                                     \
     --header 'authorization: Bearer <TOKEN>'                                           \
     --header 'content-type: application/json'                                          \
     -d '{"selector":"*my-topic//", "type":"json", "after":"my-topic/a/b/c/d/e"}'

and repeat until the final page is indicated by has_more":false.

You can set a custom page size using the size parameter.

Fetch API
Endpoint	`https://api.diffusion.cloud/topics/fetch`
Content-type	`application/json`
Method	`POST`

Fetch parameters
Parameter	Optional?	Default	Description
path	Yes	—	The Diffusion topic path as a string. It is mandatory to provide either the path or the selector.
selector	Yes	—	The Diffusion topic selector as a string. It is mandatory to provide either the path or the selector.
type	Yes	json	The topic type. Either `json` or `string`.
size	Yes	10	The number of results to return. This is used for paging results.
after	Yes	Returns results from the beginning	Specifies the start point in the topic tree, non-inclusive. This is used for paging results.

Fetch response status
Code	Description
`200`	The topic or topics were fetched successfully
`400`	There was a problem fetching values due to the parameters supplied. See `message` for more details
`500`	There was an unexpected problem fetching the values. See `message` for more details