Skip to main content

Quick Start

In this section, we will develop a more involved application in Fractl. We'll be designing the model for a blogging-service. To start, create a directory to store the model files:

mkdir blog

We need a "project" file in the blog directory to capture some meta information about the model we are developing. This project file in called model.fractl. Create this file as blog/model.fractl with the following content:

{:name :blog
 :version "0.0.1"
 :fractl-version "current"
 :components [:Blog.Core]}

The meta-data about the model is expressed as an edn-map of key-value pairs. The following keys are required in this map:

  1. :name - the unique name of the model
  2. :version - the version of the model
  3. :fractl-version - the version of the Fractl runtime required to run the model
  4. :components - a list or vector of the components where the business objects of the model are defined

The blog model has just one component - :Blog.Core. Now we need to define this component. The file in which we define the component has to be in a directory structure that matches its name - so we create the file blog/blog/core.fractl with the following content:

(component :Blog.Core)

(entity :BlogPost
 {:Name {:type :String
         :guid true}
  :Title :String
  :Content :String
  :PostedBy :Email
  :PostedOn :Now})

In the :Blog.Core component we have a single entity called :BlogPost. Its definition is self-explanatory - a blog-post is made up of a title and content. It also captures information on who created the post and when. The :Name attribute requires some explanation - it's a string-value that must be unique for each blog-post - because it's used to uniquely identify a blog-post in the system. (:guid means globally-unique-identifier - this could be any string or numeric value that uniquely identifies an instance of a :BlogPost in the system).

The basic blog-application is almost ready. Now we need to create a configuration file that will be used by Fractl for running this application. Create the file blog/config.edn with the following settings:

{:service {:port 8080}
 :store {:type :h2 :dbname "./data/blog"}}

This configuration will direct Fractl to start the blog-service on port 8080 and store its data in the H2 database file - data/blog.

At this stage, the project folder should look like:

/blog
  - config.edn
  - model.fractl
  - /blog
      - core.fractl

To test the model, run the following command from the root blog directory:

fractl run

The blog-service should start listening for incoming HTTP request on port 8080. Let's try to create a blog entry:

curl -X POST http://localhost:8080/api/Blog.Core/BlogPost \
  -H 'Content-Type: application/json' \
  -d '{"Blog.Core/BlogPost": {"Name": "post01", "Title": "Hello world", "Content": "This is my first post", "PostedBy": "mm@fractl.io"}}'

The service will allow us to interact with the entities defined in the model over a RESTful API. As the preceding command shows, invoking POST _e/Blog.Core/BlogPost with a JSON encoded :BlogPost object will create and persist a new :BlogPost instance in the system. A success response to the POST request will be,

[{
	"status": "ok",
	"result": [{
		"type-*-tag-*-": "entity",
		"-*-type-*-": "Blog.Core/BlogPost",
		"Title": "Hello world",
		"Content": "This is my first post",
		"PostedBy": "mm@fractl.io",
		"PostedOn": "2023-09-19T13:23:40.755039609",
		"Name": "post01"
	}]
}]

Note that Fractl has filled-in the :PostedOn attribute with the current date-time value, which is what the :Now datatype is supposed to do. We can use the value of the :guid attribute - :Name - to lookup, update or delete the blog-post instance.

Some REST API calls you may try on your own are shown below:

  1. Lookup a blog-post by its globally-unique-identifier or :guid.
curl http://localhost:8080/api/Blog.Core/BlogPost/post01
  1. Lookup all instances of the :BlogPost entity.
curl http://localhost:8080/api/Blog.Core/BlogPost
  1. Update an instance by its :guid.
curl -X PUT http://localhost:8080/api/Blog.Core/BlogPost/post01 \
  -H 'Content-Type: application/json' \
  -d '{"Data": {"Title": "Hello, World", "PostedBy": "jj@fractl.io"}}'
  1. Delete an instance by its :guid.
curl -X DELETE http://localhost:8080/api/Blog.Core/BlogPost/post01

Now that we've tested the model, we are ready to make a build for release:

fractl build

This will create a standalone jar file of the blog-application in the out directory. You may now launch this application using the Java virtual machine:

java -jar out/blog/target/blog-0.0.1-standalone.jar -c config.edn

In the next step of this tutorial, we will add more features to the blog-application, and in that process, explore Fractl in more depth.