POSTMAN

Send Roam Blocks data to any third party API! The name of the script is postman.

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("postman");
if (!existing) {
  var extension = document.createElement("script");
  extension.src = "https://roamjs.com/postman.js";
  extension.id = "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

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

Emoji Key

Other Extensions