This is a first explanation of the Graph API that I’ve added to this blog to allow it to be explored within our Liquid Space interface.
To try it out, go to http://liquidspace.global/ and use the [G] icon in the tools menu, and enter this “endpoint” https://jrnl.global/wp-json/graph-api/v1/query
This lets you explore this blog as a graph. Currently it’s really inefficient in several ways, but the ways to optimise it are obvious, but not worth worrying about until after our Demo in December. It also has a feature that lets you request a list of types from the blog, and retrieve nodes by type. I think I want to get rid of that and just have a starting node which links to nodes for the classes which link to the things in that class. The real value only appears when you get to an actual node in the graph and use the menu on the “card” to see the “graph links” and open more. This user experience needs work!
API
The goal for this API is to allow humans to pick stuff out of the bigger graph, so you need enough information for a human. Everything is unicode. I make the dangerous assumption that IDs for nodes don’t contain commas and a similar one for link types.
The API has two actions…
?action=ident
This is also the default behavior. It tells us a bit of data about what this endpoint can do, and that it speaks this API. I feel that wrapping small systems, like this blog, is a different issue to wrapping huge datasets, like wiki data. I think I should add a suggested “start node” option which for wordpress would be “classes” which would link to nodes representing each class of record (page,post,comment,tag…) and those would link to all the things in that set. For giant datasets maybe it could include example node IDs, or maybe we need a way to search?
Try it: https://jrnl.global/wp-json/graph-api/v1/query?action=ident
?action=nodes&ids=foo,bar,baz
Try it: https://jrnl.global/wp-json/graph-api/v1/query?action=nodes&ids=post/33
This returns a list of nodes, unsurprisingly. The basic nodes contain minimal information; just and ID and a human readable label.
Try it: https://jrnl.global/wp-json/graph-api/v1/query?action=nodes&ids=post/33
If you add &data=true you also get a “data” element on each node with whatever metadata. This is inspired by GeoJson which is a way to bind any data to geographic features.
Try it: https://jrnl.global/wp-json/graph-api/v1/query?action=nodes&ids=post/33&data=true
You can ask for linked nodes using &follow=* (you can ask for types of link only, but I realise that there’s not yet a way to know what options would be available… suggestions welcome)
Try it: https://jrnl.global/wp-json/graph-api/v1/query?action=nodes&ids=post/33&follow=*
And…. that’s about it for now. It’s super basic. I think it needs a few more features but I want something dead easy for other people to implement.
It’s a sketch of an idea, and there may already be something similar out there we should use instead, but this has the merit of being really easy for someone to add to their software.