These parameters are available for all json requests.

name	description	default
cb	adds a callback (JSONP) to the API reply	none

For authorization, add an authorization header, either:

Authorization: apikey $key

or

Authorization: bearer $token

The token can be got from the /jwt endpoint, see below.

• /jwt
• /verify-jwt
• /request_password_reset and /password_reset
• /metamodel
• /openapi
• Universe /universe and /universe/$version and /universe/version
• /errors and /errors/$errorid
• /menu
• Data Queries /data/*
  • Queries /data/$module/$entity/query
  • Query Count /data/$module/$entity/query/count
  • Count /data/$module/$entity/count
  • Entity Transitions List /data/$module/$entity/transitions
  • Entity Transition /data/$module/$entity/transitions/$transition
  • Entity Transition with dereferencing /data/$module/$entity/transitions/$transition/deref
  • Workflow /data/$module/$entity/workflow
  • Tree /data/$module/$entity/tree
  • Instance Retrieval /data/$module/$entity/$instance_id
  • Instance Query /data/$module/$entity/$instance_id/query
  • Instance Log /data/$module/$entity/$instance_id/log
  • Instance Transition List /data/$module/$entity/$instance_id/transitions
  • Instance Transition /data/$module/$entity/$instance_id/transitions/$transition
• /plugins/$plugin_name

/jwt

Get a JSON Web Token. The issued token will be valid for 24 hours.

POST /jwt

#!json
{
    "password" : "password",
    "user"     : "username"
}

Reply:

{
"token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJqd3QuY2xhaW0uY3JlYXRpb25UaW1lc3RhbXBAVVRDIiA6ICIyMDE3LTExLTMwVDA4OjQyOjU5LjIxODQwNyIsICJqd3QuY2xhaW0uZXhwaXJhdGlvblRpbWVzdGFtcEBVVEMiIDogIjIwMTctMTItMDFUMDg6NDI6NTkuMjE4NDA3IiwgImp3dC5jbGFpbS5yb2xlcyIgOiBbInF1ZXVlX3Byb2Nlc3NvciIsInJvb3QiXSwgImp3dC5jbGFpbS5jbGllbnRJZCIgOiAxLCAiand0LmNsYWltLmZpcnN0TmFtZSIgOiAicm9vdCIsICJqd3QuY2xhaW0ubGFzdE5hbWUiIDogInJvb3QiLCAiand0LmNsYWltLmxvZ2luTmFtZSIgOiAicm9vdCIsICJqd3QuY2xhaW0ucHJlZmVycmVkTGFuZ3VhZ2UiIDogImVuIiwgImp3dC5jbGFpbS5lbWFpbEFkZHJlc3MiIDogIm5vcmVwbHlAZXhhbXBsZS5jb20iLCAiand0LmNsYWltLmxhc3RMb2dpbkF0dGVtcHQiIDogIjIwMTctMTEtMjlUMjA6MTc6MTcuODIyNjk4In0.GFmp8qaOB1owVBfkd78TwHd_xbkb6TShzTKK645WPyLHKL843cv_MJintl7ywrS0W12PNZNtZI4PHdBfPn7wgQ"
}

/verify-jwt

Check the token in the Authorization header (note: this only works for bearer tokens, not apikeys)

GET /verify-jwt

Valid token:

#!json
{
    "payload": {
        "jwt.claim.loginName": "root",
        "jwt.claim.creationTimestamp@UTC": "2018-03-09T08:59:28.749207",
        "jwt.claim.firstName": "root",
        "jwt.claim.lastLoginAttempt": "2018-03-09T09:55:39.995937",
        "jwt.claim.roles": [
            "query_cache_builder",
            "query_validator",
            "queue_processor",
            "root"
        ],
        "jwt.claim.emailAddress": "noreply@example.com",
        "jwt.claim.clientId": 1,
        "jwt.claim.expirationTimestamp@UTC": "2018-03-10T08:59:28.749207",
        "jwt.claim.preferredLanguage": "en",
        "jwt.claim.lastName": "root"
    },
    "valid": true,
    "header": {
        "typ": "JWT",
        "alg": "HS512"
    }
}

Invalid token:

#!json
{
    "error": {
        "code": "403",
        "desc": "Forbidden",
        "uri": "http://46.101.130.36:3000/verify-jwt",
        "message": "authentication failed - check bearer token or api key"
    }
}

/request_password_reset and /password_reset

See Changing-Passwords

/metamodel

Returns the db model in xml.

GET /metamodel

#!xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="xenesis.xsl"?>
<application name="ironapp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="xenesis.xsd">
<module name="cash_register" label="cash register module" description="The cash register contains all transactions of a company.">
<entity name="tx" label="Transaction" description="A list of transaction entries" delete="false" translatable="false">
<attributes>
<attribute name="employee" label="Employee" description="Link to employee" datatype="bigint" required="true" translatable="false"/>
<attribute name="company" label="company" description="Link to company" datatype="bigint" required="true" translatable="false"/>
<attribute name="tx_timestamp" label="TX timestamp" description="Timestamp of the transaction" datatype="timestamptz" required="true" translatable="false"/>
<attribute name="amount" label="Amount" description="Amount of transaction" datatype="numeric" required="true" translatable="false"/>
<attribute name="currency" label="Currency" description="Currency of transaction" datatype="bigint" required="true" translatable="false"/>
<attribute name="product" label="product" description="Consumed product" datatype="bigint" required="true" translatable="false"/>
</attributes>
<restrictions>
<unique>
<unique-attribute name="employee"/>
<unique-attribute name="tx_timestamp"/>
</unique>
...

/openapi

THIS IS CURRENTLY BROKEN

GET /openapi

#!yaml
swagger: '2.0'
info:
  version: 'v1'
  title: 'genesis core api'
  description: 'This is an API to the genesis core functionality'
produces:
  - application/json
consumes:
  - application/json
schemes:
  - http
securityDefinitions:
  basicAuth:
    type: basic
    description: HTTP Basic Authentication. Works over `HTTP`
  Bearer:
    type: apiKey
    name: Authorization
    in: header
    description: JWT based authentication used in Authentication header
host: '46.101.130.36:3000'
basePath: /
paths:
  /jwt:
    get:
      security:
        - basicAuth: []
      responses:
        '200':
          description: Returns the JWT token upon successful basic authentication using username and password.

Universe /universe and /universe/$version and /universe/version

/errors and /errors/$errorid

GET /errors

#!json
[
    {
        "entity": "data_type",
        "errorType": "REQUIRED",
        "involvedAttributes": [
            "modifying_action"
        ],
        "errorID": 1,
        "module": "constant",
        "errorDescription": "required"
    },
    {
        "entity": "data_type",
        "errorType": "REQUIRED",
        "involvedAttributes": [
            "modifying_client"
        ],
        "errorID": 2,
        "module": "constant",
        "errorDescription": "required"
    },

GET /errors/2

#!json
{
    "module": "constant",
    "errorDescription": "required",
    "errorID": 2,
    "involvedAttributes": [
        "modifying_client"
    ],
    "errorType": "REQUIRED",
    "entity": "data_type"
}

/menu

Returns the menu for the current user.

GET /menu

#!json
{
"data": [
    {
        "is_link": false,
        "name": "assignment",
        "children": [
            {
                "label": "system_client",
                "name": "system_client",
                "children": [],
                "is_link": true
            },
            {
                "label": "system_entity",
                "is_link": true,
                "name": "system_entity",
                "children": []
            }
        ],
        "label": "assignment"
    },
...

Data Queries /data/*

These endpoints retrieve and manipulate the actual data in the database.

NOTE: boolean values are not returned as true/false, but 1/0 integer values. This is due to the API using Perl which does not have boolean types.

Attributes containing file data will return that meta-data, for more information on handling files see Storing-Files.

A reply can have these keys:

{
    "data"  : "this can be a hash or an array",
    "meta"  : {},
    "error" : {},

}

If an error occurs, the http response code will not be 200 and the "error" key will be present. Otherwise, the call has been successful and "data" and "meta" will be returned.

NOTE: In debug mode, the API returns 'generated_query' for some endpoints in the meta data. Please only use them for debugging queries - they will not be present when deployed:

#!json
    "meta" : {
        "generated_query": [
            "(SELECT me.modifying_action, me.modifying_client, me.modification_time, me.instance_entity, me.id, me.successor, me.context, me.key, me.value FROM ui.label() me LIMIT ?)",
            [
                {
                    "sqlt_datatype": "integer"
                },
                "10"
            ]
        ]
    }

Queries /data/$module/$entity/query

Query Count /data/$module/$entity/query/count

Returns only the "meta" portion of a query, so under "filtered" the number of entries which the query would return is found.

Count /data/$module/$entity/count

The estimatedCount is available in the universe, but currently is not being updated. This endpoint will query the database for a current count.

This count will only work to the defined huge limit, so if the value returned is equal to the maximum count, the entity has at least that many rows, maybe more.

#!json
{
    "meta": {
        "huge_limit": "1000000"
    },
    "data": {
        "count": 6
    }
}

Entity Transitions List /data/$module/$entity/transitions

List all (type create) transitions available for this entity - see Transitions

Entity Transition /data/$module/$entity/transitions/$transition

Execute a (type create) transition - see Transitions

Entity Transition with dereferencing /data/$module/$entity/transitions/$transition/deref

see Transitions

Workflow /data/$module/$entity/workflow

For entites which have a worklow defined, 'workflowUrl' and 'workflowVerb' will be set in the universe and this endpoint returns a graphic representation of that workflow.

Tree /data/$module/$entity/tree

Visualize the data in this entity as a tree - only available is the entity's strucutre defines a tree like structure (flag 'isTree' in universe).

Instance Retrieval /data/$module/$entity/$instance_id

Look in the universe for the correct url ('instanceRetrievalUrl') and verb ('instanceRetrievalVerb').

Make sure to read Referenced-Instances to understand how to retrieve referenced instances.

GET /data/extensions/query/163

{
    "data": {
        "modifying_action": 218,
        "attrs": null,
        "is_default": 0,
        "successor": null,
        "instance_entity": 63,
        "entity": 63,
        "modifying_client": 1,
        "owning_client": 1,
        "conds": null,
        "name": "xx",
        "instance_state": null,
        "modification_time": "2018-04-19 14:33:06.318505",
        "id": 163,
        "is_valid": 1,
        "error_log": null
    }
}

Instance Query /data/$module/$entity/$instance_id/query

Look in the universe for the correct url ('instanceQueryUrl') and verb ('instanceQueryVerb').

Works analog to Queries, per default retrieves all 1:1 relations and takes conds and attrs parameters.

Make sure to read Referenced-Instances to understand how to retrieve referenced instances.

POST /data/extensions/query/163/query

{
    "meta": {
        "generated_query": [
            "(SELECT me.modifying_action, me.modifying_client, me.modification_time, me.id, me.successor, me.entity, me.owning_client, me.name, me.conds, me.attrs, me.is_valid, me.is_default, me.error_log, me.instance_state, owning_client.id, owning_client.first_name, owning_client.last_name, owning_client.login_name, owning_client.password, owning_client.language, owning_client.password_validation_period, owning_client.locked, owning_client.number_of_unsuccessfull_login_attempts, owning_client.email, owning_client.modifying_action, owning_client.modifying_client, owning_client.modification_time, owning_client.successor, modifying_client.id, modifying_client.first_name, modifying_client.last_name, modifying_client.login_name, modifying_client.password, modifying_client.language, modifying_client.password_validation_period, modifying_client.locked, modifying_client.number_of_unsuccessfull_login_attempts, modifying_client.email, modifying_client.modifying_action, modifying_client.modifying_client, modifying_client.modification_time, modifying_client.successor, entity.id, entity.name, entity.label, entity.description, entity.module, entity.is_successor_not_required, entity.is_translatable, entity.is_functional, entity.is_potentially_huge, entity.modifying_action, entity.modifying_client, entity.modification_time, entity.successor, successor.modifying_action, successor.modifying_client, successor.modification_time, successor.id, successor.successor, successor.entity, successor.owning_client, successor.name, successor.conds, successor.attrs, successor.is_valid, successor.is_default, successor.error_log, successor.instance_state FROM ui.query() me LEFT JOIN system.client() owning_client ON owning_client.id = me.owning_client LEFT JOIN system.client() modifying_client ON modifying_client.id = me.modifying_client LEFT JOIN system.entity() entity ON entity.id = me.entity LEFT JOIN ui.query() successor ON successor.id = me.successor WHERE ( me.id = ? ))",
            [
                {
                    "dbic_colname": "me.id",
                    "sqlt_datatype": "bigint"
                },
                "163"
            ]
        ]
    },
    "data": {
        "modifying_client": {
            "login_name": "root",
            "last_name": "root",
            "locked": null,
            "id": 1,
            "password_validation_period": null,
            "email": "noreply@example.com",
            "number_of_unsuccessfull_login_attempts": null,
            "password": "15f387d6d56522516a14affa99be6e02",
            "modification_time": "2018-04-15 23:18:26.415611",
            "language": 1,
            "modifying_client": 1,
            "modifying_action": 29,
            "successor": null,
            "first_name": "root"
        },
        "entity": {
            "modification_time": "2018-04-15 23:18:34.349169",
            "name": "query",
            "is_translatable": 0,
            "is_functional": 0,
            "is_successor_not_required": 0,
            "id": 63,
            "label": "Query",
            "successor": null,
            "modifying_action": 5,
            "description": "Arbitrary queries as defined in dbix, http://search.cpan.org/~ribasushi/DBIx-Class-0.082840/lib/DBIx/Class.pod",
            "is_potentially_huge": 0,
            "module": 6,
            "modifying_client": 1
        },
        "owning_client": {
            "modifying_client": 1,
            "first_name": "root",
            "successor": null,
            "modifying_action": 29,
            "id": 1,
            "password_validation_period": null,
            "locked": null,
            "last_name": "root",
            "login_name": "root",
            "language": 1,
            "number_of_unsuccessfull_login_attempts": null,
            "password": "15f387d6d56522516a14affa99be6e02",
            "modification_time": "2018-04-15 23:18:26.415611",
            "email": "noreply@example.com"
        },
        "modifying_action": 218,
        "attrs": null,
        "successor": null,
        "is_default": 0,
        "is_valid": 1,
        "error_log": null,
        "id": 163,
        "instance_state": null,
        "modification_time": "2018-04-19 14:33:06.318505",
        "conds": null,
        "name": "xx"
    }
}

Instance Log /data/$module/$entity/$instance_id/log

Get the history of an instance from the logs. Look in the universe for the correct url ('instanceLogUrl') and verb ('instanceLogVerb').

POST /data/system/entity/3/log

{
    "meta": {
        "generated_query": [
            "(SELECT me.modifying_action, me.modifying_client, me.modification_time, me.instance_entity, me.id, me.successor, me.entity, me.owning_client, me.name, me.conds, me.attrs, me.is_valid, me.is_default, me.error_log, me.instance_state FROM (SELECT me.modifying_action, me.modifying_client, me.modification_time, me.instance_entity, me.id, me.successor, me.entity, me.owning_client, me.name, me.conds, me.attrs, me.is_valid, me.is_default, me.error_log, me.instance_state FROM ui.query() me WHERE ( id = ? ) UNION SELECT me.modifying_action, me.modifying_client, me.modification_time, me.instance_entity, me.id, me.successor, me.entity, me.owning_client, me.name, me.conds, me.attrs, me.is_valid, me.is_default, me.error_log, me.instance_state FROM ui_log.query me WHERE ( id = ? )) me LIMIT ?)",
            [
                {
                    "sqlt_datatype": "bigint",
                    "dbic_colname": "id"
                },
                "163"
            ],
            [
                {
                    "sqlt_datatype": "bigint",
                    "dbic_colname": "id"
                },
                "163"
            ],
            [
                {
                    "sqlt_datatype": "integer"
                },
                "10"
            ]
        ],
        "total": 7,
        "huge_limit": "1000000",
        "filtered": 1,
        "selected": 1
    },
    "data": [
        {
            "instance_state": null,
            "modification_time": "2018-04-19 14:33:06.318505",
            "conds": null,
            "name": "xx",
            "is_valid": 1,
            "error_log": null,
            "id": 163,
            "modifying_action": 218,
            "is_default": 0,
            "successor": null,
            "attrs": null,
            "entity": 63,
            "modifying_client": 1,
            "instance_entity": 63,
            "owning_client": 1
        }
    ]
}

Instance Transition List /data/$module/$entity/$instance_id/transitions

see Transitions

Instance Transition /data/$module/$entity/$instance_id/transitions/$transition

see Transitions

/plugins/$plugin_name

Call the corresponding plugin (as defined in the universe).

POST /plugins/generate_uuid

{
    "result": {
        "uuid": "1b23e61e-2074-4d51-f24a-f49e47d16631"
    },
    "success": 1
}

see Plugins