https://github.com/hyperwell/gateway

🏰 Serving distributed Web Annotations from the decentralized web
https://github.com/hyperwell/gateway

annotation decentralization gateway hyperswarm ldp p2p w3c-web-annotations

Last synced: 15 days ago
JSON representation

🏰 Serving distributed Web Annotations from the decentralized web

• Host: GitHub
• URL: https://github.com/hyperwell/gateway
• Owner: hyperwell
• License: mit
• Created: 2019-09-12T13:57:54.000Z (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2022-04-11T19:29:29.000Z (about 2 years ago)
• Last Synced: 2024-03-04T20:37:06.886Z (4 months ago)
• Topics: annotation, decentralization, gateway, hyperswarm, ldp, p2p, w3c-web-annotations
• Language: JavaScript
• Homepage: https://kassel.works/hyperwell
• Size: 1010 KB
• Stars: 27
• Watchers: 4
• Forks: 1
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Lists

• awesome-stars - hyperwell/gateway - 🏰 Serving distributed Web Annotations from the decentralized web (JavaScript)

README

        
# Hyperwell Gateway

[![DOI](https://zenodo.org/badge/208063924.svg)](https://zenodo.org/badge/latestdoi/208063924)

Proof-of-concept implementation of a peer-to-peer (P2P) system that leverages collaboration, local-first principles, and more on [W3C Web Annotations](https://www.w3.org/TR/annotation-model/). The system provides software for local nodes that store annotations, as well as a gateway server that implements the [Web Annotation Protocol](https://www.w3.org/TR/annotation-protocol/).

For establishing an environment of [local-first applications](https://www.inkandswitch.com/local-first.html) for collaborative annotation, we store collections of annotations called **notebooks** in [Hypermerge](https://github.com/automerge/hypermerge) documents. These documents are distributed via the [hyperswarm](https://github.com/hyperswarm/hyperswarm) decentralized network and merged without conflicts via [automerge](https://github.com/automerge/automerge).

The Hyperwell gateway aims to bridge the decentralized network and the web, offering collaborative annotation to Linked Data systems and web-based annotation environments alike by implementing the W3C Web Annotation specifications. For users, the gateway aims to offer institutional affiliation and archiving.

![Hyperwell architecture](architecture.png)

We laid out the motivation behind the decentralized annotation architecture of Hyperwell in our 2020 paper, [‘From Me to You: Peer-to-Peer Collaboration with Linked Data‘](https://zenodo.org/record/3750243). For more on Hyperwell and the journey behind it: https://kassel.works/hyperwell

**Important**: This is alpha software for research. Your annotations will be available publicly and accessible without authentication. This software has not been professionally audited.

## Usage

Run a gateway server via `npm start` or `./bin/server.js`. The CLI accepts the following arguments:

- `--port ` (`-p`): The port number to listen on. Defaults to `3000`. Example: `--port 8080`.

- `--host `: The public hostname. Defaults to `localhost:3000`. Example: `--host www.example.com:8080`

- `--ssl` (`-s`): Whether the gateway is served via SSL. This will not make the gateway actually terminate HTTPS requests (it listens for standard HTTP requests), but will transform annotation IDs accordingly, using the `https:` scheme. Defaults to `false` (not set).

## API

The gateway exposes a web-based API as a superset of the [Web Annotation Protocol](https://www.w3.org/TR/annotation-protocol/), including support for batch operations as well as subscribing to real-time updates on notebooks via the WebSocket protocol. In the following, the `` identifier corresponds to the notion of [‘containers’](https://www.w3.org/TR/ldp/#ldpc) on the LDP. We simply use a hexadecimal encoding of the respective Hypermerge document URL (`hypermerge://abc123...`) for URL safety. `` corresponds to the ID of an annotation within a notebook, which commonly is a [UUID](https://tools.ietf.org/html/rfc4122) string.

- `/annotations/`. REST endpoint for operations on an entire notebook. This endpoint supports retrieval of all of its annotations (`GET`) and creation of new a new annotation (`POST`).

- `/annotations//`. REST endpoint for operations on a particular annotation within a notebook. This endpoint supports retrieval (`GET`), editing (`PUT`), and deletion (`DELETE`).

- `/annotations/batch/`. REST endpoint for batch operations on a notebook. This endpoint supports batch creation (`POST`), batch edits (`PUT`), and batch deletions (`DELETE`).

- `/annotations/subscribe/`. WebSocket endpoint for subscribing to changes on a notebook. Upon initiating a connection via the standard WebSocket protocol, the gateway will send messages as soon as the respective notebooks receives changes.

(tbc).

## License

MIT License, see [`./LICENSE`](/LICENSE).