All-in-One Documentation

Introduction:

This document serves as an all-in-one guide to continue/get started with or replicate the work done by the Nova interns in June/July of 2024.

Contents

1. Running the Fluree Server Image with Docker

2. Using Postman to Conduct HTTP Requests

   2.1 Creating a Fluree Ledger using Postman

   2.2 aia-o in Postman

   • 2.2.1 Automatically creating the request body

   2.3 Example transaction + fluree transaction syntax

   2.4 Exporting a Postman transaction

3. RDF in JSON-LD

   3.1 Properties

   3.2 Classes and subclasses

1. Fluree Server Image from Docker:

To create a Fluree Server image from Docker:

• Ensure you have Docker installed.
• Open a Command Line Interface (CLI) such as Command Prompt (Windows) or Terminal (Mac).
• Adjust and run the following command:

docker run -d -p 58090:8090 --name fluree_server3 fluree/server

💡 NOTE: The docker run command given above does not store any changes made to the container itself or the data it contains. This means if we were to run the container and create a Fluree ledger and transact data to this ledger, once the container is stopped (either with the docker stop command or by accident) the ledger and the data it contains will be lost. When the container is run again in the future all of the transactions will need to be performed again to add the data. This is useful when new transactions are tested and one does not want each transaction to make permanent changes to a ledger. Once you are done testing the transactions you simply stop the docker container and don't have to worry about manually cleaning up/deleting files on your local computer.

The following command allows you to mount a local directory to /opt/fluree-server/data inside the container so that the data that Fluree writes to disk can be persisted locally, allowing your data state to be persistent beyond the lifetime of the container itself.

docker run -p 58090:8090 -v `pwd`/data:/opt/fluree-server/data fluree/server

• The -d command is used to run the docker container in the background ("detached mode") so that the terminal window can still be used to send more prompts.
• The -p command specifies the port the server will use locally.
• The text following –name is the name of the Docker container pulled from the Fluree server image. This can be changed depending on the user’s preference. If not specified, Docker will automatically assign a unique name to the container.
• Docker will automatically pull the latest version of the fluree/server image and run it if it is not found on your local device.
• In your CLI, you can type docker ps which should show the running fluree/server container.
• You can now send HTTP requests to the local URL which has been created using port 58090 (or another port, depending on which one you specified). To view the HTTP API endpoint page, visit https://localhost:58090.
• To stop the container from running, use the command docker stop followed by either the --name specified in the run command above or the container ID, which can be found by running the docker ps command. Alternatively, the Docker Desktop interface can be used to run/stop containers or manually pull images from Docker Hub.

docker ps

A useful intro video on Docker can be found here

2. Using Postman to Conduct HTTP Requests

Find out more about Postman.

💡 NOTE: Before starting with Postman, ensure you have a Fluree server up and running.

I recommend going through Fluree's cookbook example and Forking their Postman collection. The cookbook can be found here. Click the orange Run in Postman button, or alternatively you can fork the collection here.

2.1 Creating a Fluree Ledger using Postman

1. Create a Collection in Postman
2. In the newly added collection, add a Post request

💡 NOTE: There are 3 different types of URLs when interacting with the Fluree server. This is an example of the URLs, although the port might look different depending on how you assigned it:

1. If this is your first request and you do not have an existing Fluree Ledger: http://localhost:58090/fluree/create
2. If you wish to conduct insert, update or delete transactions to your existing ledger: http://localhost:58090/fluree/transact
3. If you want to perform queries on your ledger: http://localhost:58090/fluree/query

3. After using the /fluree/create/ URL you can now type the the body of the HTTP request in JSON-LD format. For more examples of RDF syntax in JSON-LD, see this section
4. After typing the body you can simply hit the Send button.

2.2 aia-o in Postman

I highly recommend going through the aia-o "cookbook". It is a thorough and complete overview of how to use Fluree and Postman together and also provides all the needed transactions to add aia-o to a Fluree Ledger. The cookbook also provides curl transactions for users who are using the terminal.

The aia-o cookbook can be found here.

2.2.1 Automatically creating the Fluree request body

Integrating updates to aia-o

The following section details a (preliminary) workflow for continuously integrating conceptual changes made to aia-o with the version in the Fluree ledger. In the future, these steps may be incorporated into a CI workflow with GitHub Actions, triggered by an update to aia.owl in this repo.

1. Edit the ontology file in Protégé

2. Export in Turtle format (.ttl)

3. createFlureeTransaction/main/py to create the request body. Navigate to ./createFlureeTransaction and run:

   python3 main.py path/to/input.ttl <ledger name> path/to/output.json
   

4. Use cURL for the transaction

    curl -X POST \
     -H "Content-Type: application/json" \
     --data-binary "<path/to/json/file>" \
     http://localhost:<port>/fluree/<create/insert/etc.>
   

2.3 Example: a simple aia-o transaction (Postman + JSON-LD):

Explanation

In the example above we add Bob the farmer. He is 53 years old and works with Tom, who is also a farmer. The above transaction could be a create request if the ledger "ex_ontology" does not exist yet and the URL in the request is a /fluree/create URL. It could also be a regular insert transaction if the URL is fluree/transact and the ledger exists already.

A normal Fluree insert transaction consists of 3 parts:

1. The "@context" section: This section consists of a set of prefixes for URLs. Take a look at the example above: the "ex" is a prefix for http://example.org. Now every time we wish to refer to this particular URL, we only have to use ex:.

💡 NOTE: In every transaction you have to provide the context for each prefix you use again. It is not possible to use ```ex:``` in the next transaction without providing the context for the URL again.

2. Ledger: Here you simply provide a new name for the ledger you wish to create, or provide the name of an existing ledger on the Fluree Server to insert Bob the farmer to this ledger.

3. Insert: This keyword specifies what you wish to achieve with this transaction. Each entity you insert should be placed after "insert": in between a set of curly brackets {}. If you are adding more than one entity you simply add another set of curly brackets and place a comma after the previous entity.

   • Each entity/node requires an "@id" which can uniquely identify it in this particular ledger. Because there is no other Bob in this entity we simply use the "@id": "Bob". Bob is not found in the example.org vocabulary, thus he does not use the prefix "ex:".

   • We can give each entity properties for example, name, age, marital status, employment status etc., provided the example.org vocabulary has a property for age, name and worksWith, and also a class for Farmer. We can assign these properties to Bob.

2.4 Exporting a Postman request

It is possible to convert Postman's requests to other formats such as curl, R (using httr), Python, C# etc.

1. Click on the request
2. Select the </> icon on the right side
3. Select a format from the drop-down list that will appear
4. Copy and paste the converted request as needed

RDF vocabulary examples in JSON-LD:

3.1 RDF Properties:

• This adds a property "married", which is an RDF property. It also adds the "married" property for Bob.
• Married is not called from a vocabulary and thus is used without a prefix. This also means this property only exists in the ledger.
• Please note the "rdf" and "rdfs" prefixes in the "@context" section.

3.2 RDF Classes and Subclasses: {#class}

3.2.1 RDF Classes

• The snippet above assumes there is an entity in the example vocabulary "ex: Location". This entity has type "rdfs:Class".

3.2.2 RDF Subclasses

• The snippet above assumes Country is also an entity from ```example.org``
• We want to assign a relationship which states it is a subclass of Location in our dataset. Please take a look at how the syntax and declaration for the "rdfs" subclass work in the example above.

3.2.3 Inserting data using the Classes:

• We can simply now add "South-Africa" as an entity which is of type "ex:Country" and then by the rules we provided is a subclass of "ex:Location".