POSTMAN

Send Roam Blocks data to any third party API!

Installation

You could use the Copy Extension button below to individually install this extension. To install, just paste anywhere in your Roam graph and click "Yes, I Know What I'm Doing".

Manual Installation

If instead you prefer to manually install, first create a block with the text {{[[roam/js]]}} on any page in your Roam DB. Then, copy and paste this code block as a child of the block.

var existing = document.getElementById("roamjs-postman");
if (!existing) {
  var extension = document.createElement("script");
  extension.src = "https://roamjs.com/postman.js";
  extension.id = "roamjs-postman";
  extension.async = true;
  extension.type = "text/javascript";
  document.getElementsByTagName("head")[0].appendChild(extension);
}

Usage

When the extension is installed, it will set up a config page for you at roam/js/postman like the one below:

The structure of the config is as follows:

  • apis - The set of all endpoints you have configured to hit. Each child is labelled with the tag that the extension will detect to send data.
    • url - The url of the API, set as the child of this block. Values could be interpolated with the following variables:
      • {id} - The block reference id of the current block
    • body - The data to send on the POST request. Each child of body is a key and each child of the key is a value. Values could be interpolated with the following variables:
      • {id} - The block reference id of the current block
      • {block} - The text contents of the current block. Use {block:clean} to omit the tag used to setup the endpoint.
      • {tree} - The full contents of the block tree, in a stringified JSON. Use {tree:text} to get the tree in a plain text format and {text:html} to get the tree in a HTML format.
    • headers - The set of headers to send with the request, useful for sending Authorization or other headers. Just like body, each child represents the header name, and the child of the header name is the header value.

The image above renders an icon next to any #[[PostmanExample]] tags. Clicking the icon on a block that says Send This! #[[PostmanExample]] would send the following request:

{
    "url": "https://api.roamjs.com/postman",
    "body": {
        "foo": "bar",
        "block_content": "Contents: Send This! #[[PostmanExample]]",
        "tree_content": "{}",
    },
    "method": "POST",
    "headers": {
        "Content-Type": "application/json"
    } 
}

The RoamJS postman endpoint is available to help test your configuration. The config page should include the URLs that you actually want to hit for each tag.

Custom Bodies

By default, Postman parses the configuration under body as a key value string map. You could specify unique types on any given value or on the body itself by specifying one of the following:

  • {string}
  • {boolean}
  • {number}
  • {array}
  • {object}

The body has a default type of {object}. We could change this by using one of the other four options above. The following configuration will send an array of three strings as the body:

- body {array}
  - foo
  - bar
  - baz

All other values have a default type of {string}. See the example below for how to specify a value of each type:

This example would send the following body:

{
    "booleanKey": true,
    "numberKey": 5,
    "stringKey": "foo",
    "arrayKey": [
        "foo",
        "bar",
        "baz",
    ],
    "objectKey": {
        "foo": "bar",
        "baz": "hello, world"
    }
}

Demo

Contributors

This extension is brought to you by RoamJS! If you are facing any issues reach out to support@roamjs.com or click on the chat button on the bottom right. If you get value from using this extension, consider sponsoring RoamJS by clicking on the button below!

A special thanks to those who's contributions also helped make this extension possible:

ROAMJS DIGEST

Add your email below to stay up to date on all RoamJS features, fixes, and news!

Other Extensions