---
tags: thoughts
---
# Universal Documents API

The idea behind universal documents is that each document is also an application with a builtin API that allows other universal documents to connect, embed and/or interrogate it.

As described in [Universall Documents and Cobalt](https://hackmd.io/zyVnPfOORWm0yrb8bakjew) making the document also be an appliction with an API is not that difficult. The document just needs to add a header with a stable link to the application, written in javascript or web assembly. e.g:

<script src="https://example.com/document.js"></script><!--

The API itself should be built on top of the postMessage browser API, which is available in iframes and web workers, among others.

## Meaningful Data and Querying

However, what the API should look like is quite a bit more difficult. There should be a way to support API negotiation and introspection. There should be some fallback catch-all API's that are easy to support in all kinds of documents. But for a meaningful integration or cooperation between applications, there is a need for meaningful data.

Fortunately there is already a lot of work going on to solve exactly this problem, in the [Solid](https://solidproject.org/) community. They are using Linked Data as the way to add meaning to data. The only difference between Solid and Universal Documents, is that solid seperates applications from their data and data storage. But if you ignore that part, and base advanced, useful document API's on the same linked data concept, I think a large part of the research and running code from the Solid community can be used as-is.

I think there's a real chance of creating bridges between the two approaches, based on the shared linked data.

One of the main problems is querying a document for specific data. [Ruben Verborgh](https://ruben.verborgh.org/) has built a query language and API called [LDFlex](https://ruben.verborgh.org/blog/2018/12/28/designing-a-linked-data-developer-experience/#ldflex), that is really simple to use.

## Messages and Namespaces

The other problem is how to avoid naming conflicts in the API. The lowelevel API is build on postMessage. That has no namespacing support, so we need to add that in a default message format. Each message should have an identifier that defines the API it is part of. This identifier should have a namespace. The simplest scalable namespace I know of is the Java namespace syntax. But I propose that instead of the '.' seperator convention we use the '/' as seperator, and start and end with a '/' as well. This is because the '.' has special meaning in javascript and it might be misunderstood.

/com/example/something/

In addition I think that a simple way to build an API with support for lots of different messages is to use the Routing pattern that is already well known to web developers. However, this is an implementation detail that doesn't have to be part of any official standard.

api.route.add('/com/example/do-something/', (msg) => {
    return doSomething();
});

Just like a webserver responds to messages with a path in it, so could a Universal Document also respond to messages with a path in it. I'm not sure adding the whole Verb thing is a good idea, but who knows.

Because I don't want to poison the namespace in advance, the experiments in the github repository will use a specific root name to indicate they are experimental. This namespace will always be available and unmanaged:

/x/your-message-names/