API Documentation

Grimoire.org runs on a Neo4j graph database backend. This means that each piece of data in the database is a node, and pieces of data are connected by relationships. For example, the grimoire Grimorium Verum and the demon Sugat are both nodes, and their relationship is that Grimorium Verum lists the demon Sugat.

Anatomy of a node

Each node is represented as a json object. Bold keys (props, identifier, uid, link, id, and label) are present on all nodes, and unbolded keys are arbitrary across different nodes.

Grimorium Verum

{ "props": { "buy": "http://www.amazon.com/gp/product/1434811166?ie=UTF8&camp;=1789&creativeASIN;=1434811166&linkCode;=xm2&tag;=grimoireorg-20", "uid": "grimorium-verum", "date": 1817, "identifier": "Grimorium Verum", "online_edition": "http://www.hermetics.org/pdf/grimoire/Grimoirum_Verum.pdf", "date_precision": "year" }, "parent_label": "parent:book", "link": "/grimoire/grimorium-verum", "id": 2, "label": "grimoire" }

Meanings of the Keys

props information fields about the node {"uid": "...", "identifier": "...", ...}
uid unique human-readable id, used in urls grimorium-verum
identifier display title for the node Grimorium Verum
link formatted link to node (/label/uid) /grimoire/grimorium-verum
id Neo4j internal id 2
label the type of data represented by the node grimoire

The optional key parent_label is an additional label used to group related labels. For example, grimoire and book are both under the parent label parent:book.

Each page on grimoire.org corresponds to a single node, and its url is defined by the uid of that node. However, the a page may include additional related nodes, such as excerpts, images, or events.

Relationships

Nodes are connected to each other by relationships. All relationships are directional, which means they have a start, end, and type (as well as a relationship id). For example, Grimorium Verum and Surgat have the following relationship:

{ "start": "grimorium-verum", "end": "surgat", "type": "lists" "id": 1511, }

This relationship can be read as "the grimoire Grimorium Verum lists the demon Surgat."

Endpoints

This is a very short list, and represents only a tiny portion of the kind of queries that could be run on the database. If you have questions or requests, please email me at mousereeve@riseup.net, and I will be happy to see what I can do.

GET /api/v1/label

Get a list of labels.

Example

/api/v1/label

GET /api/v1/label/label

Get a list of nodes for a given label.

Params

limit maximum values returned (default: 25, maximum: 100)
offset a positive integer (default: 0)
sort order results by a given property name on the nodes
sort_direction "asc" or "desc" (default: "asc")
random randomize results order; setting this to True overrides sorting (default: False)
uids_only return a list only containing uids (default: False)

Example

/api/v1/label/grimoire?limit=10

GET /api/v1/node/uid

Get a node based on the node's uid.

Params

relationships include relationships to the node (default: False)

Example

/api/v1/node/grimorium-verum

/api/v1/node/grimorium-verum?relationships=True

GET /api/v1/node/uid/label

Get all connected nodes of type label for a given uid.

Params

limit maximum values returned (default: 25, maximum: 100)
offset a positive integer (default: 0)
random randomize results order; setting this to True overrides sorting (default: False)

Example

/api/v1/node/lesser-key/excerpt