HTTPS SSH

dingsda

dingsda - ze internez of dings

https://www.dingsda.org

test web UI (optimized for mobile): https://www.dingsda.org/two

at the moment: invite only. Feel welcome to contact philip(├Ąt)machinaex(dot)de to get a test account.

documentation

function documentation (so far only of server.js not yet from the clients) can be found at https://dingsda.org/docs/

visual schematic documentation of the client - server - database flows and (later) the livecycle of an HTTP request against the dingsda API can be found further down at schemata

API v0.1

HTTP API running from node script:

server.js:

known issues - not propper RESTful API because commands part of JSON payload instead of url endpoint. will be changed till v1.0.0, but atm not hightest priority (sorry, noob mistake)

dependencies: - nano (^7.1.0) - https (^1.0.0) - express (^4.16.4) - request (^2.88.0) - cookie-parser (^1.4.3) - body-parser (^1.18.3) - uuid/v5 (^3.3.2) - cors (^2.8.4) - http-proxy (^1.17.0) - deepcopy ^1.0.0

configuration

configuration for server.js and pushServer_test is to be found within the config_file server_config.json

configuration for the UIs is found inside of UI/<ui number>/config_UI.json

make sure to provide all necessary information before you start the server.

HTTP API

the dingsda API knows 3 different entry levels:

  1. Instance Level (http requests to URL instanceUrl + API_BASE_URL will be considered Instance Level and handled within server.js by the function instanceCommander())

for example: https://dingsda.org:3000/api/v1 This level is mainly to manage user Authentication, login, subscriptions etc

  1. Database Level (http requests to URL instanceUrl + API_BASE_URL + username will be considered DB level and handled by function DBCommander())

for example: https://dingsda.org:3000/api/v1/machinaex This level is the server endpoint users will interact the most with, as it represents the user's database and handles all requests that do concern more than one item. This also means: It will only be relevant for the user owning the DB addressed

  1. Ding Level (http requests to URL instanceURL + API_BASE_URL + <username> + <item _id> will be considered dinglevel and be handled by function dingsCommander())

for example: https://dingsda.org:3000/api/v1/machinaex/29e5cf8f-a99c-571c-93ab-e24fad18d2be This level is only handling requests that aim for single items in a database. It usually concerns owners of the item and people who the item is shared with or anyone who is allowed to read the items info (e.g. if it is set to be publicly visible)

requests to API need AuthSessionToken within its cookies all times except for Authentication.

Important: All POST API endpoints MUST be JSON formatted and follow this basic form:

{
  "data":[
    {
    "type":"<name of command type>",
    "<other fields>": {}
    }
  ]
}

1. Instance Level API

GET:

Authentication:

GET:

parameter description
name username to authenticate with
password password

see: verifyUserCredibility()

description: <br>verifies user Auth by testing for username and password inside of request query parameter. username and password can be query parameters or in json format inside of a query parameter calles json. e.g.: https://xxx.xxx/yyy?username=aaa&password=bbb or https://xxx.xxx/yyy?json='{"username":"aaa","password":"bbb"}'

response: AuthSessionCookie that can and will be saved by the browser

examples:

curl:

$ curl -X GET 'https://dingsda.org:3000/api/v1?name=jan&password=demopassword'

POST:

(CURRENTLY NOT USED. SEE dingslevel/findItems)

{
  "type":"search",
  "doc": {...}
}

see: search()

examples: (...)


2. Database Level API

GET:

DB Infos:

returns: CouchDB Infos about DB.

note: for testing. probably to be deprecated later.


POST:


ADD ITEMS

json:

"data":[
  {
    "type":"addItems",
    "doc": {<doc to be added>}
  }
]
parameter description
doc doc to be added.

see: addItem()

behaviour:


UPDATE ITEMS

json:

"data":[
  {
    "type":"updateItems",
    "doc": {<doc to be updated>}
  }
]
parameter description
doc doc to be updated, including recent _rev(!)

see: update()

behaviour:

updates item handed over in doc. needs to provide the most recent


DELETE ITEMS

json:

"data":[
  {
    "type":"deleteItems",
    "doc": {<doc to be deleted>}
  }
]
parameter description
doc doc to be deleted, including recent _rev(!)

see: deleteItems()

behaviour:


FIND ITEMS

json:

"data":[
  {
    "type":"findItems",
    "doc":<mango style searchTerm>
  }
]
parameter description
doc searchQuery: object w/ { key : searchvalue }
bookmark (OPTIONAL) bookmark string from last result.

see: update()

behaviour: Will search Database for documents matching the searchterm(s) specified in json-field data.doc

This API will only simplify all requests to use either "$regex":"(?i)" or "$in": in front of the searchValue. So: Search for searchValue will be successfull if searchValue is in any way included (within array or as substring) inside doc.

Note: in order to keep the API flat, it uses a dot notation (parent.child) for requests deeper down the object tree (e.g. parent.child:"hans" instead of parent:{child:"hans"}) (also: s.example below)

If you want to search more DBs at once and/or make real [mango queries] (https://github.com/cloudant/mango) to dingsda, use the search API endpoint on instance Level.

The query response result is limited to a maximum of 50 found items. The optional bookmark field can be added to follow up query in order to get the next 50 items returned. (see couchDBs find() API for more details on bookmarks behaviour)

returns: JSON formatted list of objects matching the searchQuery, but only contains the following fields: "_id","name","location","other","owners","hyperlink","inPossessionOf". For more Information about the objects, a FETCH on Dings level is recommended

examples:

client js/jquery:

var data =
{
    "data":
    [{
        "type":"findItems",
        "doc":{
                 "location.address": "India"
            }
    }]
}

var settings = {
  "url": "https://dingsda.org:3000/api/v1/jan",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "data": JSON.stringify(data)
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

--->

{
    "docs": [
        {
            "_id": "1e862072-b279-5b84-b0ed-98eca77e21db",
            "name": "Samsonite Rollkoffer carry-on",
            "location": {
                "address": "jogishvari, Jogeshwari Road, Chamunda Colony, Amraiwadi, Ahmedabad, Gujarat 380026, India",
                "latitude": "22.258652",
                "longitude": "71.19238050000001"
            },
            "other": {
                "tags": [
                    "Tools",
                    "Travel",
                    "Reise"
                ],
                "visibility": [
                    "public"
                ],
                "description": "2 compartments",
                "borrowable": "not"
            },
            "owners": [
                "jan"
            ],
            "hyperlink": "https://dingsda.org:3000/api/v1/jan/1e862072-b279-5b84-b0ed-98eca77e21db"
        }
    ],
    "bookmark": "g1AAAAB4eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYqrGKZamBkZmBvpJhmZW-qaJlmY6CYZpKboWlqkJieam6caGaYkgfRywPQSrSsLAGuGH_M"
}

<div id="markdown-header-schemata">

schemata

you find different visual documentations of the data flow and the client - server / database architecture of dingsda inside of /img

chema client-server-db: schema client-server-db

templating flow and dependencies of client two: templating flow and dependencies of client two

--------------------------------

json schema (work in progress NOT UP TO DATE!!!)

explanation needed for: - location either string (then: constraint free because only for humans anyhow) or object (than one of two constraints) are valid and force longitude and latitude via pattern or the field "inside_id" to mark in which other item it can be found - other contains everything that is not absolutely needed for the simplest bare bone item (that includes: barcodes, prices, sizes, availablity etc.)

{
  "$id": "https://dingsda.org/api/v1/item.json",
  "description": "Schema for an item within dingsda.org DB. Describes a thing in as minimal terms as possible",
  "definitions": {
    "location": {
      "type": "object",
      "description": "minimal requirements for a location object.",
      "properties": {
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "longitude": {
          "type": "string",
          "pattern": "^(\\+|-)?(?:180(?:(?:\\.0{1,6})?)|(?:[0-9]|[1-9][0-9]|1[0-7][0-9])(?:(?:\\.[0-9]{1,6})?))$"
        },
        "latitude": {
          "type": "string",
          "pattern": "^(\\+|-)?(?:90(?:(?:\\.0{1,6})?)|(?:[0-9]|[1-8][0-9])(?:(?:\\.[0-9]{1,6})?))$"
        },
        "insideOf": {
          "type": "string"
        },
      },
      "required": [
        "name",
        "longitude",
        "latitude"
      ]
    }
  },
  "type": "object",
  "properties": {
    "_id": {
      "type": "string",
      "description": "unique ID to identify item."
    },
    "name": {
      "type": "string",
      "description": "human readable name"
    },
    "location": {
      "type": [
        "string",
        "object"
      ],
      "oneOf": [
        {
          "$ref": "#/definitions/location"
        },
        {
          "$ref": "#/definitions/obj_in_obj"
        },
        {
          "type": "string"
        }
      ],
      "description": "physical location of the object at the moment. either string describing location or object following location definition."
    },
    "owners": {
      "type": [
        "string",
        "array"
      ]
    },
    "other": {
      "$id": "/properties/other",
      "type": "object",
      "properties": {
        "price": {
          "$id": "/properties/other/properties/price",
          "type": "string",
          "title": "The Price Schema "
        },
        "visibility": {
          "$id": "/properties/other/properties/visibility",
          "type": [
            "string",
            "array"
          ]
          "title": "Read Rights for this item",
          "description": "needs to be either keywords 'private', 'public' or an Array of groups listed in _security of owners DB"
        }
      }
    }
  },
  "required": [
    "_id",
    "name",
    "location",
    "owners"
  ]
}

this simple example would pass validation:

{
    "_id":"1",
    "name":"eins",
    "location":{"name":"berlin","longitude":"52.51704","latitude":"13.38792"},
    "owner":["machinaex"],
    "other":{}
}