This is the demo instance of Restagraph. Welcome!

What it is

An HTTP API in front of a graph database (neo4j), that applies constraints to create, read and update requests according to a user-definable schema. It's intended to be an engine for a structured knowledge-management system.

The schema definitions are similar in spirit to SQL's DDL (Data Definition Language) and RDF's SHACL (SHApe Constraint Language), though it's much simpler than the latter.

You can define

• Resourcetypes: named types of things, complete with the named attributes that each type can have.
• Relationships: also named, these are directional. You define them with lists of permissible source and destination types.
  • There isn't a way of setting attributes on a relationship.
  • There are other constraints that you can define; see Defining a schema for more details.

You can also upload files, and create relationships between them and other resources.

The schema is defined inside the database; Restagraph reads that, and autogenerates an HTTP API that bears a passing resemblance to the REST architecture. You can just use a command-line tool such as curl, but it's much easier with a graphic interface like the one you're reading this on.

It encourages you to think deeply and clearly about the meaning and structure of things, and the relationships between them, so it rewards a more considered approach. If you're looking for something to stand up quickly so you can knock out tasks and GSD without overthinking it, this isn't it.

Features

• HTTP API
  • It's just plain HTTP, using the methods in their intended manner.
  • The URIs it generates are consistent and predictable, making it nice and easy to build things on top of it.
  • It's designed specifically to enable you to build your own UI on top (hello, accessibility!) and/or any automation you find useful.
• User-definable schemas
  • Define your own schemas as JSON files that you upload to the server.
    • Each time you upload a definition, it's added to the existing schema definitions.
    • The server auto-generates the API according to the combined set of definitions.
    • This means you can define multiple subschemas, and combine them to suit your needs.
    • Schemas are versioned, so you can create a new one for a clean start and/or for experimentation, and roll back to a previous one if an experiment doesn't work out.
• File upload/download
  • Files have their own API for uploading and downloading.
  • Their metadata is stored in the same way as any other resource, meaning you can link other types of things to/from them.
    • This also makes it easy to build things like image galleries, with customised filtering.
• Versioned resources
  • When you edit a resource, a new version of its user-defined attributes is automatically created.
  • You can fetch a previous version.
  • You can set any version to be the "current" version, i.e. the version that's returned when you don't ask for one in particular, providing rollback/rollforward capabilities.
• Authentication
  • Built-in username/password system.
    • This uses a separate Neo4j database by default, as a security measure.
  • LDAP is also supported, at a relatively basic level.
• Authorisation policies
  • The current options are very simple, but effective:
    • open: anybody can read and edit
    • write-authenticated: anybody can read, but only logged-in users can edit
    • authenticated-only: only logged-in users can read or edit
    • read-only: archive mode.

What do you mean by "structured"?

Things like Wikipedia and Obsidian are great as far as they go, but each page is just a blob of text - if you want structure, you have to put it into the text yourself, with markup.

In Restagraph, you define resourcetypes, each of which has a user-defined set of attributes, enabling you to . Each attribute is defined with a datatype (text blob, varchar with maximum length, integer or boolean). For example, People might have separate fields for year of birth, year of death, and any notes you want to record about them. This way, you know exactly where to reach for a given chunk of information about each kind of thing.

Where to get it

If you just want to get started with using it, you can download Docker images from Docker Hub.

If you want to get your hands dirty, you can clone the source-code from Codeberg.

More information

The best starting points are What is Restagraph? and the conceptual overview, but from there just follow the links within the text and (more usefully) at the bottom of each page.

If you're looking for API documentation, it's linked from the Restagraph Application page.

What do you mean it's a separate thing?

Restagraph itself is an HTTP API server, and doesn't have a graphic interface. You can interact with it at the command line using curl, but even I only do that when I'm troubleshooting. This website is just a front-end to that API.

You can build your own that's optimised for your needs.

What are these hyperlinks at the bottom of each page?

These are the interconnections between things, which give them context and thus more meaning.

Importantly, these are separate from hyperlinks in the text on a page. These are actually stored in the database, so when you rename a thing, all these links automatically follow it, in a way that text hyperlinks don't.

Contact

If you have any questions or, better yet, feedback, please email me at restagraph at electronic-quill.net