Roam API

[agentydragon]

Describe the problem

Roam would be way more useful for me if I could integrate it into other systems that I use with an API. It would allow me to actually interlink a large part of my digital life into the Roam knowledge graph.

Sorry if I'm duplicating this. I didn't find any issue with the "API" string on this GitHub repo. If there's already discussion/status updates about this going on somewhere, I'd appreciate if you could share the link.

Here's a few examples of apps that I think would be good to integrate, and what you could do with it:

• Google stuff
  • Calendar
  • Linking events (and meeting notes) between Roam and Calendar
  • Showing calendar events in Roam daily pages
  • Linking Roam TODOs / other tag with Google reminders
  • Tasks
  • Linking Roam TODOs / other tag with Google tasks (i.e.: check off Google task --> Roam block gets marked done, and the other way around)
  • Google Contacts
  • Link from person page in Roam to Google contact
  • Automatically create person page when I have a new contact in Google Contacts
  • Gmail
  • Linking mails to Roam, with autocomplete
  • Keep
  • One-way sync into Roam ("move all text notes into Roam, nested under #[[Keep import]]")
• Pocket
  • Create Roam page from highlights, tags in Pocket
• Exist.io
  • Link mood, daily custom tags into Roam daily pages
  • Other tracking (energy in/out, productive time, time spent in apps, ...)
• Anki
  • I often create Anki card from reminders to make a card I stored in Roam. An Anki plugin could let you link to Roam pages/blocks inside Anki notes.
• IMDB
  • Import watched movies and ratings into Roam
• Goodreads
  • Import books read, in "want to read" etc. into Roam
• Facebook
  • Link people in Roam to Facebook profile
• Trello

Feature implementation

Here's my wishlist for what the API should allow, roughly by priority:

• CRUD on blocks
• API documentation
• Search for incoming links to a page
• General search
• Search by attributes (see #75)
• CRUD for hidden-by-default metadata on blocks/pages (for purposes of integrations - e.g. so that the integration can save "Roam page ABC corresponds to entity 12345 in other system X")
• Extending the Roam web app
  • Custom /-commands - e.g.:
  • /facebook -> autocomplete pop-up -> type person's name -> enter -> expands into Facebook link
  • Custom JavaScript operations operating on Roam pages
  • /task -> take content of current block, create a page with that title and attributes Type:: Task, Status:: TODO, replace the block with a link to the page and navigate to the page
• Graph queries over multiple nodes - e.g.:
  • Find all pages with Type:: Task and Status:: Blocked that have #[[Project Aubergine]] in Tags:: or any page pointed to by their Project:: attribute has #[[Project Aubergine]] in Tags::.
  • (= "find tasks on Project Aubergine that are blocked")
  • FYI, one pre-existing standardized graph query language is SPARQL.

[steveraysteveray]

SPARQL could work. Also GraphQL is a possibility that might be easier to integrate, since it speaks JSON. But definitely on board with the idea of a query language!

[agentydragon]

Also, to mention more explicitly something I sort of put between the lines:

I'd like it if Roam mapped well into RDF data (https://en.wikipedia.org/wiki/Semantic_triple) and into the Linked Data ecosystem - i.e., nodes that are URLs, typed edges, typed nodes. There's a whole ecosystem and standards for interlinking databases from different sources, querying, existing standard language for describing types and definitions of common types, etc.

Roam's model of "nodes are basically a nested bullet list" does not fit into it directly at the moment. Linked Data edges have to be typed and directed. Roam edges are not typed and bidirectional (except attributes). But I think it could be fit reasonably well.

Linked Data conformance is orthogonal to having an API. But still, using Linked Data as a base would allow Roam to benefit from all the experience and standardization work that's gone into it. It might take a bit to shoehorn Roam to fit that model, but it might save a bunch of wheel-reinvention.

[steveraysteveray]

I don't think it would be hard to map to RDF. Basically something like:

[jontaylor]

Without API support

• Data is locked in other applications, this errodes the position of Roam over time, instead of locking people into it
• The app becomes work needlessly as continual copy and pasting is required to keep a central view
• The data that goes into Roam is only as powerful as the views/queries/reports/analytics within the web UI, this is OK for a research application, but locks you out of executive power users or managers
• Sharing snippets of information is not possible, you lose the entire scope of teams/ business use cases

What you can do with an API

• Data can be loaded into the platform and updated automatically, roam can become central to workflow, rather than (if I remember/have time) peripheral tool
• Weaknesses or purposeful limitations built into the application can be worked around
• The community can enhance the application further, acting as a force multiplier for internal development

As a user who makes use of Roam for use in an executive role, I am becoming increasingly aware that I may not be part of the targetted user base. It makes me anxious about if an investment of time into this is a smart move. Some idea of the direction or intended user base would be useful.

[artpi]

I really hope for a "real" API. In the meantime, I'm working using this: https://github.com/artpi/roam-research-private-api

[fivestones]

Excited for this feature to come out!

[samching]

Any updates on this?

[agentydragon]

Thanks @artpi for the repo. I've ported a bit of it into Rust and played around a little.

Roam devs: window.roamPrivateAPI as it exists right now only lets us do things within a running Roam tab. That's not a good developer experience, for at least these reasons:

• I don't want to have to write JavaScript. My automation is a bunch of Rust and Python.
• I want my integrations to be headless. If I use window.roamPrivateAPI to make a headless integration right now, I have to do something like run a headless Puppetteer, like @artpi's code does.
  • Browser automation is slow and flaky. With my port of the basic approach @artpi took, it takes my script more than a minute to log into Roam and get ready to talk to the API.
  • It requires you to pipe data into a separate JS sandbox (in the tab).
  • (For background: for me, it's not possible to automate some things in plain JS embedded in Roam. I want to do XHR calls to Interactive Brokers Flex Query API, which is behind a CORS origin whitelist.)

Please, implement support for some API that is easy to talk to outside a browser, like a REST or WebSocket API. (Or if that's not possible for some reason, at least a JS client library that wouldn't require a browser to run. I'd prefer to not have to launch a JS runtime to talk to Roam, but it's at least better than having to spawn Chrome.)

For extra dev experience points, it would be nice if you could do basic operations (like "add block", "get block text") without having to construct/parse EDN, because most programming languages are not Clojure. But using some an EDN parser library is less of a pain than launching a background browser...