3. Getting Started

3.1. Concept of DATAGERRY

DATAGERRY is an asset management tool (or CMDB), where you can define the data model for your own.

In DATAGERRY objects are stored. An object can be for example a router, server, location or maintenance contract and consists of multiple fields (e.g. management IP, hostname, … of a router). Each field has a specific data type. A datatype could be for example text, checkbox, date, dropdown or many more. The blueprint for an object is defined in an object type.

Object Types are the blueprints for objects. They define the following details for all objects of that type:

  • fields and their datatype

  • object type icon

  • object type name

  • external links

The object type definition can be changed at any time, even if objects of that type already exists. In DATAGERRY we ensure, that only fields that are defined in the type definition were shown.

3.2. Quick Start

To get started with DATAGERRY, do the following steps:

  • Add a new Category for Objects (menu: Framework -> Category)

  • Add a new Object Type (menu: Framework -> Types)

  • Add Objects for your Object Type (menu: Framework -> Objects)

2. User Management — DATAGERRY bugfix-NET-972_json-export-of-objects-incorrect-5512885dacc1fd7be9da74e16ad36ec53e34cfb3 documentation

2. User Management

2.1. Users

GET /users/

HTTP GET/HEAD rest route. HEAD will be the same result except their will be no body.

Example request:

GET /rest/users/ HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1000
X-Total-Count: 1
X-API-Version: 1.0

{
   "results": [
        {
          "public_id": 1,
          "user_name": "admin",
          "active": true,
          "group_id": 1,
          "registration_time": "2020-01-01 00:00:00.000000",
          "authenticator": "LocalAuthenticationProvider",
          "email": null,
          "password": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
          "image": null,
          "first_name": null,
          "last_name": null
        }
  ],
  "count": 1,
  "total": 1,
  "parameters": {
    "limit": 10,
    "sort": "public_id",
    "order": 1,
    "page": 1,
    "filter": {},
    "optional": {}
  },
  "pager": {
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  },
  "pagination": {
    "current": "http://datagerry.com/rest/users/",
    "first": "http://datagerry.com/rest/users/?page=1",
    "prev": "http://datagerry.com/rest/users/?page=1",
    "next": "http://datagerry.com/rest/users/?page=1",
    "last": "http://datagerry.com/rest/users/?page=1"
  },
  "response_type": "GET",
  "model": "User",
  "time": "2020-01-01 00:00:00.000000"
}
Query Parameters
  • sort – the sort field name. default is public_id

  • order – the sort order value for ascending or descending. default is 1 for ascending

  • page – the current view page. default is 1

  • limit – max number of results. default is 10

  • filter – a mongodb query filter. default is {} which means everything

Request Headers
Response Headers
Status Codes
GET /users/(int: public_id)

HTTP GET/HEAD rest route for a single resource by its ID.

Example request

GET /rest/users/1 HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
    "result": {
        "public_id": 1,
        "user_name": "admin",
        "active": true,
        "group_id": 1,
        "registration_time": "2020-01-01 00:00:00.000000",
        "authenticator": "LocalAuthenticationProvider",
        "email": null,
        "password": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
        "image": null,
        "first_name": null,
        "last_name": null
    },
    "response_type": "GET",
    "model": "User",
    "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
POST /users/

HTTP POST route for inserting a new user.

Example request

POST /rest/users/ HTTP/1.1
Host: datagerry.com
Accept: application/json

{
    "user_name": "test",
    "active": true,
    "group_id": 2,
    "password": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 100
Location: http://datagerry.com/rest/users/2
X-API-Version: 1.0

{
  "result_id": 2,
  "raw": {
        "public_id": 2,
        "user_name": "test",
        "active": true,
        "group_id": 2,
        "registration_time": "2020-01-01 00:00:00.000000",
        "authenticator": "LocalAuthenticationProvider",
        "email": null,
        "password": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
        "image": null,
        "first_name": null,
        "last_name": null
    },
  "response_type": "INSERT",
  "model": "User",
  "time": "1970-01-01T00:00:00"
}
Request Headers
Response Headers
Status Codes
PUT /users/(int: public_id)

HTTP PUT/PATCH route for updating a existing user.

Example request

PUT /rest/users/1 HTTP/1.1
Host: datagerry.com
Accept: application/json

{
    "public_id": 1,
    "user_name": "admin",
    "active": false,
    "group_id": 1,
    "registration_time": "2020-01-01 00:00:00.000000",
    "authenticator": "LocalAuthenticationProvider",
    "email": null,
    "password": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
    "image": null,
    "first_name": null,
    "last_name": null
}

Example response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: 100
Location: http://datagerry.com/rest/users/1
X-API-Version: 1.0

{
    "result": {
        "public_id": 1,
        "user_name": "admin",
        "active": false,
        "group_id": 1,
        "registration_time": "2020-01-01 00:00:00.000000",
        "authenticator": "LocalAuthenticationProvider",
        "email": null,
        "password": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
        "image": null,
        "first_name": null,
        "last_name": null
    },
    "response_type": "UPDATE",
    "model": "User",
    "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
DELETE /users/(int: public_id)

HTTP DELETE route for deleting a existing user.

Example request

DELETE /rest/users/1 HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
    "deleted_entry": {
        "public_id": 1,
        "user_name": "admin",
        "active": false,
        "group_id": 1,
        "registration_time": "2020-01-01 00:00:00.000000",
        "authenticator": "LocalAuthenticationProvider",
        "email": null,
        "password": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
        "image": null,
        "first_name": null,
        "last_name": null
    },
  "response_type": "DELETE",
  "model": "User",
  "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes

2.2. Groups

GET /groups/

HTTP GET/HEAD rest route. HEAD will be the same result except their will be no body.

Example request:

GET /rest/groups/ HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1000
X-Total-Count: 1
X-API-Version: 1.0

{
   "results": [
        {
            "public_id": 1,
            "name": "admin",
            "label": "Administrator",
            "rights": [
                {
                    "level": 0,
                    "name": "base.*",
                    "label": "base.*",
                    "description": "Base application right",
                    "is_master": true
                }
            ]
        }
  ],
  "count": 1,
  "total": 1,
  "parameters": {
    "limit": 10,
    "sort": "public_id",
    "order": 1,
    "page": 1,
    "filter": {},
    "optional": {}
  },
  "pager": {
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  },
  "pagination": {
    "current": "http://datagerry.com/rest/groups/",
    "first": "http://datagerry.com/rest/groups/?page=1",
    "prev": "http://datagerry.com/rest/groups/?page=1",
    "next": "http://datagerry.com/rest/groups/?page=1",
    "last": "http://datagerry.com/rest/groups/?page=1"
  },
  "response_type": "GET",
  "model": "Group",
  "time": "2020-01-01 00:00:00.000000"
}
Query Parameters
  • sort – the sort field name. default is public_id

  • order – the sort order value for ascending or descending. default is 1 for ascending

  • page – the current view page. default is 1

  • limit – max number of results. default is 10

  • filter – a mongodb query filter. default is {} which means everything

Request Headers
Response Headers
Status Codes
GET /groups/(int: public_id)

HTTP GET/HEAD rest route for a single resource by its ID.

Example request

GET /rest/groups/1 HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
    "result": {
        "public_id": 1,
        "name": "admin",
        "label": "Administrator",
        "rights": [
            {
                "level": 0,
                "name": "base.*",
                "label": "base.*",
                "description": "Base application right",
                "is_master": true
            }
        ]
    },
    "response_type": "GET",
    "model": "Group",
    "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
POST /groups/

HTTP POST route for inserting a new group.

Example request

POST /rest/groups/ HTTP/1.1
Host: datagerry.com
Accept: application/json

{
    "name": "test",
    "label": "test",
    "rights": [
        "base.framework.object.*"
    ]
}

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 100
Location: http://datagerry.com/rest/groups/3
X-API-Version: 1.0

{
    "result_id": 3,
    "raw": {
        "public_id": 3,
        "name": "test",
        "label": "test",
        "rights": [
            {
                "level": 10,
                "name": "base.framework.object.*",
                "label": "object.*",
                "description": "Manage objects from framework",
                "is_master": true
            }
        ]
    },
    "response_type": "INSERT",
    "model": "Group",
    "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
PUT /groups/(int: public_id)

HTTP PUT/PATCH route for updating a existing user.

Example request

PUT /rest/groups/3 HTTP/1.1
Host: datagerry.com
Accept: application/json

{
    "public_id": 3,
    "name": "test",
    "label": "Test",
    "rights": [
        "base.framework.object.*"
    ]
}

Example response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: 100
Location: http://datagerry.com/rest/groups/3
X-API-Version: 1.0

{
    "result": {
        "public_id": 3,
        "name": "test",
        "label": "Test",
        "rights": [
            "base.framework.object.*"
        ]
    },
    "response_type": "UPDATE",
    "model": "Group",
    "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
DELETE /groups/(int: public_id)

HTTP DELETE route for deleting a existing user.

Note

Group with PublicID 1 (Admin) & 2 (User) can not be deleted!

Example request

DELETE /rest/groups/3 HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
    "deleted_entry":  {
        "public_id": 3,
        "name": "test",
        "label": "Test",
        "rights": [
            {
                "level": 10,
                "name": "base.framework.object.*",
                "label": "object.*",
                "description": "Manage objects from framework",
                "is_master": true
            }
        ]
    },
    "response_type": "DELETE",
    "model": "Group",
    "time": "2020-01-01 00:00:00.000000"
}
Query Parameters
  • action – Parameter of GroupDeleteMode. MOVE will push all users in this group to passed group_id and DELETE will delete all users in this group.

  • group_id – The PublicID of the group which the MOVE action will be use.

Request Headers
Response Headers
Status Codes

2.3. Rights

Note

The right routes are static.

GET /rights/

HTTP GET/HEAD rest route. HEAD will be the same result except their will be no body.

Example request:

GET /rest/rights/ HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response:

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
    "results": [{
         "level": 0,
         "name": "base.*",
         "label": "base.*",
         "description": "Base application right",
         "is_master": true
    }],

    "count": 1,
    "total": 62,
    "parameters": {
        "limit": 1,
        "sort": "name",
        "order": 1,
        "page": 1,
        "filter": {},
        "optional": {
            "view": "list"
        }
   },
   "pager":{
        "page": 1,
        "page_size": 1,
        "total_pages": 62
   },
   "pagination": {
        "current": "http://datagerry.com/rest/rights/",
        "first": "http://datagerry.com/rest/rights/?page=1",
        "prev": "http://datagerry.com/rest/rights/?page=1",
        "next": "http://datagerry.com/rest/rights/?page=2",
        "last": "http://datagerry.com/rest/rights/?page=62"
   },
   "response_type": "GET",
   "model": "Right",
   "time": "2020-01-01 00:00:00.000000"
}
Query Parameters
  • sort – the sort field name. default is name.

  • order – the sort order value for ascending or descending. default is 1 for ascending

  • page – the current view page. default is 1

  • limit – max number of results. default is 10

  • filter – a mongodb query filter. default is {} which means everything

  • optionalview parameter. Default is list.

Request Headers
Response Headers
Status Codes
GET /rights/(str: name)

HTTP GET/HEAD rest route for a single resource by its name.

Example request

GET /rest/rights/base.* HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
    "result": {
        "level": 0,
        "name": "base.*",
        "label": "base.*",
        "description": "Base application right",
        "is_master": true
    },
    "response_type": "GET",
    "model": "Right",
    "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
GET /rights/levels

HTTP GET/HEAD rest route for a all security levels.

Example request

GET /rest/rights/levels HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
  "result": {
    "CRITICAL": 100,
    "DANGER": 80,
    "SECURE": 50,
    "PROTECTED": 30,
    "PERMISSION": 10,
    "NOTSET": 0
  },
  "response_type": "GET",
  "model": "Security-Level",
  "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
  • 200 OK – Everything is fine.

2.4. Settings

GET /users/(int: user_id)/settings/

HTTP GET/HEAD rest route. HEAD will be the same result except their will be no body.

Example request:

GET /rest/users/1/settings/ HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1000
X-Total-Count: 1
X-API-Version: 1.0

{
  "results": [
    {
      "identifier": "test",
      "user_id": 1,
      "payload": {},
      "setting_type": "GLOBAL"
    }
  ],
  "response_type": "GET",
  "model": "UserSetting",
  "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
GET /users/(int: public_id)/settings/(str: identifier)

HTTP GET/HEAD rest route for a single resource by the UserID and the setting identifier.

Example request

GET /rest/users/1/settings/test HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
  "results": [
    {
      "identifier": "test",
      "user_id": 1,
      "payload": {},
      "setting_type": "GLOBAL"
    }
  ],
  "response_type": "GET",
  "model": "UserSetting",
  "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
POST /users/(int: public_id)/settings/

HTTP POST route for inserting a new setting.

Example request

POST /rest/users/1/settings/ HTTP/1.1
Host: datagerry.com
Accept: application/json

{
    "identifier" : "test",
    "user_id" : 1,
    "payload" : {},
    "setting_type" : "GLOBAL"
}

Example response

HTTP/1.1 201 CREATED
Content-Type: application/json
Content-Length: 100
Location: http://datagerry.com/rest/users/1/settings/test
X-API-Version: 1.0

{
  "result_id": "test",
  "raw": {
    "identifier": "test",
    "user_id": 1,
    "payload": {},
    "setting_type": "GLOBAL"
  },
  "response_type": "INSERT",
  "model": "UserSetting",
  "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
PUT /users/(int: public_id)/settings/(str: identifier)

HTTP PUT/PATCH route for updating a setting.

Example request

PUT /rest/users/1/settings/test HTTP/1.1
Host: datagerry.com
Accept: application/json

{
    "identifier" : "test",
    "user_id" : 1,
    "payload" : {},
    "setting_type" : "GLOBAL"
}

Example response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: 100
Location: http://datagerry.com/rest/users/1/settings/test
X-API-Version: 1.0

{
    "result": {
        "identifier": "test",
        "user_id": 1,
        "payload": {},
        "setting_type": "GLOBAL"
    },
    "response_type": "UPDATE",
    "model": "UserSetting",
    "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes
DELETE /users/(int: public_id)/settings/(str: identifier)

HTTP DELETE route for deleting a existing setting.

Example request

DELETE /rest/users/1/settings/test HTTP/1.1
Host: datagerry.com
Accept: application/json

Example response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json
Content-Length: 100
X-API-Version: 1.0

{
    "deleted_entry": {
        "identifier": "test",
        "user_id": 1,
        "payload": {},
        "setting_type": "APPLICATION"
    },
    "response_type": "DELETE",
    "model": "UserSetting",
    "time": "2020-01-01 00:00:00.000000"
}
Request Headers
Response Headers
Status Codes