HTTP / API Configuration for GAIA / blockstack.js

Sorry for bothering you guys with this support question.
I am daring to ask cause I hope there might be a simple configuration that I (being a stupid designer) just can’t figure out, but you might know by heart, as you are familiar with the Blockstack storage.

If this not as easy as I hope in my dreams … no worries.
Any guidance would be highly appreciated and made my day.

The context:

This is about currently developed with React.
So far I used for all API calls the getFile / putFile provided by blockstack.js

Now though I would love to use an external library, Annotator.js that allows users to highlight texts and to create annotations. In order to make the annotations persistent a storage module has to be configured.

This storage module can talk to any remote server that serves an HTTP API and uses JSON as its primary interchange format.
So all that sounds as if GAIA should work with this.

Though I am stuck on how I should configure the storage module, the specific URLs, so that the annotator.js can read and write to the users storages on Blockstack.

The question:

If I use standard blockstack.js so far with getFile/putFile etc. how do I have to configure the URLs below so that annotator.js reads and writes the JSON to the GAIA storage?

The code for the configuration in my React component will look something like this:

var app = new annotator.App();
app.include(, {
    prefix: '',
    create: '/annotations',
    update: '/annotations/{id}',
    destroy: '/annotations/{id}',
    search: '/search'

.then(function () {

Thanks so so much for helping out.

The following are options for the configuration of the storage module.

An introduction to the module and usage is here.
The full API documentation of the module is here.
This is the API endpoint. If the server supports Cross Origin Resource Sharing (CORS) a full URL can be used here.
Default: '/store'
The server URLs for each available action. These URLs can be anything but must respond to the appropriate HTTP method. The URLs are Level 1 URI Templates as defined in RFC6570:

        create: '/annotations',
        update: '/annotations/{id}',
        destroy: '/annotations/{id}',
        search: '/search'
Should the storage emulate HTTP methods like PUT and DELETE for interaction with legacy web servers? Setting this to true will fake HTTP PUT and DELETE requests with an HTTP POST, and will set the request header X-HTTP-Method-Override with the name of the desired method.
Default: false
Should the storage emulate JSON POST/PUT payloads by sending its requests as application/x-www-form-urlencoded with a single key, “json
Default: false
A set of custom headers that will be sent with every request. See also the setHeader method.
Default: {}

Disclaimer: I’ve never used annotator.js before, and all I’ve done to try and understand the problem is read the documentation for it.

It looks like annotator.js is meant to be used with a remote storage service that implements a well-defined RESTful API. What you might be able to do is create a modified middleware that, instead of reading and writing to the annotator server, will instead read and write to the user’s Gaia storage. The purpose of this middleware would be to call getFile() and putFile() instead of trying to fetch() to the set of annotator endpoints.

1 Like

Thanks so much for looking into this. Really appreciated!

Yeah, I was not hoping for it… but it’s getting more complicated than just setting up some URL paths ;(
As non engineer this brings me to a dark place :wink:

That said, I was tinkering with it, and I could make it work via some of the “hooks” provided by annotator.js to save the annotations and get them on to the GAIA storage.

I have though still no clue how I can make it load them and displaying them.