Skip to main content

REST API

An HTTP REST API is automatically generated by Fractl for the loaded models. This API is documented here in the context of the sample model given below.

(component :Acme.Company)

(entity
 :Acme.Company/Department
 {:No {:type :Int :guid true}
  :Block {:oneof ["a" "b"]}})

(entity
 :Acme.Company/Employee
 {:No {:type :String :id true}
  :Name :String})

(relationship
 :Acme.Company/WorksFor
 {:meta {:contains [:Acme.Company/Department :Acme.Company/Employee]}})

Headers​

The Content-Type header must be set to either application/json or application/transit+json. If authentication is enabled for the model, set the Authorization header as Bearer <auth-token>. (Please see the Identity documentation for more details).

Create​

POST /api/ComponentName/EntityName

{:ComponentName/EntityName
 {:Attribute1 value1
  ...}}

Example

POST /api/Acme.Company/Department

{"Acme.Company/Department":
 {"No": 103,
  "Block": "b"}}

Create an Entity Instance Under a :contains Relationship​

POST /api/ComponentName/ParentEntityName/parent-guid/Relationship/ChildEntityName

{:ComponentName/ChildEntityName
 {:Attribute1 value1
  ...}}

Example

POST /api/Acme.Company/Department/101/WorksFor/Employee

{"Acme.Company/Employee":
 {"No": "E101",
  "Name": "James"}}

If the parent-entity and child-entity belongs to different components, provide the fully qualified name of the child-entity in the URL, with the $ character acting as the separator - e.g Acme.Company$Employee.

It's also possible to create a parent entity-instance along with a list of its children. The following example creates a new department with two employees:

POST /api/Acme.Company/Department

{"Acme.Company/Department":
 {"No": 104,
  "Block": "b"},
  "Acme.Company/WorksFor": 
    [{"Acme.Company/Employee": {"No": "E101", "Name": "Joe"}},
     {"Acme.Company/Employee": {"No": "E102", "Name": "Mat"}}]}

Query​

The simplest query is based on the globally-unique-identifier (:guid) of the entity.

GET /api/ComponentName/EntityName/guid

Example

GET /api/Acme.Company/Department/104

To return all child instances contained by the parent, the /__tree suffix may be added to the GET URL. The following request will return the department and all its employees (under the -> key in the :Department instance).

GET /api/Acme.Company/Department/104/__tree

The GET request without the guid will return all instances of the entity.

Example

GET /api/Acme.Company/Department

Additional data-filters may be passed as query-parameters. As an example, let's try to fetch only those departments in the "b" block:

GET /api/Acme.Company/Department?Block=b

Query for Child Entities​

GET /api/Component/ParentEntity/parent-guid/ContainsRelationship/ChildEntity
GET /api/Component/ParentEntity/parent-guid/ContainsRelationship/ChildEntity/child-id

The first form will return all children from the contains-relationship. The second form will return the child instance with specified :id.

Example

GET /api/Acme.Company/Department/104/WorksFor/Employee/E101

Update​

PUT /api/ComponentName/EntityName/guid

{:ComponentName/EntityName
 {:Attribute1 new-value1
  ...}}

Example

PUT /api/Acme.Company/Department/104

{"Acme.Company/Department":
 {"Block": "a"}}

Updating Child Instances​

PUT /api/ComponentName/ParentEntityName/parent-guid/ContainsRelationshipName/ChildEntityName/child-id

{:ComponentName/ChildEntityName
 {:Attribute1 new-value-1
  ...}}

Example

PUT /api/Acme.Company/Department/104/WorksFor/Employee/E102

{"Acme.Company/Employee":
 {"Name": "Matthew"}}

Delete​

DELETE /api/ComponentName/EntityName/guid
DELETE /api/ComponentName/ParentEntityName/parent-guid/ContainsRelationshipName/ChildEntityName/child-id

Example

DELETE _e/Acme.Company/Department/104

Note By default deleting a parent will also delete all its contained-children. This can be overridden by turning-off :cascade-on-delete options in the relationship, as shown below:

(relationship
 :Acme.Company/WorksFor
 {:meta {:contains [:Acme.Company/Department :Acme.Company/Employee
                    :cascade-on-delete false]}})