Data Objects

The Collectu hub provides an easy-to-use JSON database. You can store, version, and share json-based data.

Info

JSON (JavaScript Object Notation) is a lightweight data format used for storing and exchanging structured information. It is easy to read and write for humans while being simple for machines to parse and generate. JSON represents data using key-value pairs, similar to a dictionary in many programming languages. It supports data types such as strings, numbers, booleans, arrays, and nested objects. Due to its simplicity and compatibility, JSON is widely used in web applications, APIs, and data storage.

{
  "name": "Collectu",
  "age": 5,
  "email": "info@collectu.de",
  "features": ["easy", "open"],
  "address": {
    "city": "Oberriexingen",
    "zip": "71739"
  }
}

Working Principle

In general, each data object is a json data body in a specific path on the Collectu API. The path of a data object must be unique and begin with the username of the owner, e.g. https://api.collectu.de/api/v1/data_object/user123/machines/cnc1.

The paths of data objects can be used to create nested data objects. An advanced example would be as follows:

  • user123/machines/cnc1
  • user123/machines/cnc2

If we request the nested data (include_all = true) for the path user123/machines, we get the following result:

{
    "cnc1": {
        "name": "cnc1",
        "status": "stopped",
    },
    "cnc2": {
        "name": "cnc2",
        "status": "running"
    }
}

Features

The data object service of the Collect hub offers some main features, which are explained below.

Internal and External References

Each data object can have an internal and/or external reference.

  • Internal references link the data of one data object to another data object.
  • External references link a data object's data to an external REST API. The specified endpoint must return valid JSON.
Info
The order of extraction is: external reference, internal reference, data of the data object. This means that the keys of the external reference are overwritten by the keys of the internal reference, and both references are overwritten by the data of the data object itself.

Schemas

To describe the expected data object, you can use JSON schemas. JSON Schema is a declarative language for annotating and validating JSON documents' structure, constraints, and data types.

Please find information about how to create a JSON schema here: https://json-schema.org

Warning
Referenced data (internal and external) is not validated against the schema.

Versioning

Data objects can be versioned. This means, each time an existing data object is updated, a new version is generated. This means that changes can always be tracked.

Warning
Do not use versioning if a data object is frequently updated!

Usage

Collectu offers predefined modules to request (inputs.web.collectu_data_objects_1) and publish (outputs.web.collectu_data_objects_1) data objects to the Collectu hub.

REST API

You can use our REST API to interact with our data object service. All endpoints can be found and used here: https://api.collectu.de

Authorization

If a data object is not public, you can only access it, if the correct token is provided with the request. To do this, add the following header:

{"Authorization": "Bearer your-api-access-token"}

Previous
Grafana
Next
Hooks