Documentation: Developer Integration Workflow

The Realcube API consists of three essential workflows:

1. Creating a location hierarchy
2. Locating the facilities
3. Maintaining the facilities

Getting started

Ask Uwe Forgber to create a user for you:

• Your user should have access to one or more organisations
• Your user should have the “Organisation manager” role for the organisations above

Afterwards set a password: PUT /v1/users/reset_password_instructions.

All API endpoints display if they need an authentication:

• 🔒: These routes do not need an authentication
• 🔓: These routes needs the user to be authenticated (will become a 🔒 once you are authenticated)

Furthermore, the application has three roles:

• Customer account users Are allowed to create customer attributes schemas and customer attributes schema memberships for all customer accounts they have a membership for. The customer account of an organisation can be looked up in the organisations endpoint. The customer account membership is shown in the users endpoint.
• Organisation manager: Have full access to all resources within an organisation
• Organisation member Have restricted access depending on the attribute permittet_building_ids within the organisation membership:
  • No access to all property endpoints
  • No access to all lot endpoints
  • Can only read building classifications
  • Can only CRU+ buildings where the user has the building_id within the permittet_building_ids of the building itself
  • Can only CRUD+ levels, rooms and zones where the user has the building_id within the permittet_building_ids of the building itself or its successor in the hierarchy tree
  • Can only CRUD+ facilities, building_types, activities, attachments and images that are in the hierachy of the permitted_building_ids
  • Can CR manufacturers and departments

Locations and facilities are all scoped to an organisation. Even a user might have access to many organisations it is not possible combine the contents from two different organisations. Note the organisation_id param, which will always declare in which organisation context (scope) you execute the request.

Authentication

1. Fetch your API key: POST /v1/users/log_in
2. Click on the green “Authorize” button or any open lock 🔓 and enter the API key

Program example with cURL

1. Reset the password
   curl 'https://api.realcube.com/api/v1/users/reset_password_instructions' -X PUT -H 'content-type: application/json' -H 'accept: application/json' --data-binary $'{"email": "user@example.com"}'
2. Fetch your API key
   curl 'https://api.realcube.com/api/v1/users/log_in' -H 'content-type: application/json' -H 'accept: application/json' --data-binary $'{"email": "user@example.com","password": "secret-password"}'
3. Read your current organisations (remember the ID to fetch entities within this organisation)
   curl 'https://api.realcube.com/api/v1/organisations' -H 'accept: application/json' -H 'x-api-key: secret-api-key'
4. List all properties
   curl 'https://api.realcube.com/api/v1/properties?current_organisation_id=3' -H 'accept: application/json' -H 'x-api-key: secret-api-key'
5. Create a new property
   curl 'https://api.realcube.com/api/v1/properties?current_organisation_id=3' -H 'content-type: application/json' -H 'accept: application/json' -H 'x-api-key: secret-api-key' --data-binary $'{ "name": "Siemens Park", "country": "Deutschland", "zip_code": "86159", "city": "Augsburg", "custom_id": "Maybe an internal ID you can freely choose", "comment": "A comment you can freely choose", "property_type_id": 1}'

Location hierarchy

A location is a generic term for one of these domain models:

• Property
• Lot (optional)
• Building
• Level
• Room
• Zone

Many endpoints allow to specify a polymorphic relationship to a location. These require to submit a location_type and a location_id body param.

The locations itself have a hierarchically order, whereas a lot is the only optional location node in the hierarchy.

Building units

Building units are a way to group locations and facility together. A building unit belongs to a building and can contain:

• Levels
• Rooms
• Zones
• Facilities

Facilities

Facilities are located in exactly one location, but the upper location hierarchy is cached at the facility itself. E.g. if you locate a facility in a building, a facility will return beside the building the lot and property in the hierarchy, too.

Facilities can be linked belong each other in a tree structure. To set a link between two facilities, one of them have to specify the parent_id with the ID of the other facility.

JSON Schema validation

To create or update a facility you need a valid JSON payload regarding the schema of the chosen facility type. Below there is an example for a JSON schema with a corresponding valid payload:

Schema

{
  "type": "object",
  "required": [
    "Beschreibung",
    "Rohrnetz",
    "Pumpen",
    "Armaturen",
    "Schmutzfaenger",
    "Rohrleitungen"
  ],
  "properties": {
    "Pumpen": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "Bauart",
          "Baujahr",
          "Beschreibung",
          "Durchfluss",
          "Foerderhoehe",
          "Hersteller",
          "LeistungElektrisch"
        ],
        "properties": {
          "Bauart": {
            "enum": [
              "Einpumpenanlage",
              "Doppelpumpenanlage (parallel)",
              "Mehrpumpenanlage (parallel)",
              null
            ],
            "type": [
              "string",
              "null"
            ],
            "description": "Bauart"
          },
          "Baujahr": {
            "type": [
              "string",
              "null"
            ],
            "description": "Baujahr"
          },
          "Durchfluss": {
            "type": [
              "string",
              "null"
            ],
            "description": "Durchfluss in Volumenstrom"
          },
          "Hersteller": {
            "type": [
              "string",
              "null"
            ],
            "description": "Hersteller"
          },
          "Beschreibung": {
            "type": [
              "string",
              "null"
            ],
            "description": "Beschreibung (Freitextfeld zur allgemeinen Beschreibung von Objektinformationen)"
          },
          "Foerderhoehe": {
            "type": [
              "string",
              "null"
            ],
            "description": "Förderhöhe in Meter"
          },
          "LeistungElektrisch": {
            "type": [
              "string",
              "null"
            ],
            "description": "Leistung elektrisch in Watt"
          }
        }
      },
      "description": "422.81 Pumpen"
    },
    "Rohrnetz": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "Beschreibung"
        ],
        "properties": {
          "Beschreibung": {
            "type": [
              "string",
              "null"
            ],
            "description": "Beschreibung (Freitextfeld zur allgemeinen Beschreibung von Objektinformationen)"
          }
        }
      },
      "description": "422.80 Rohrnetz"
    },
    "Armaturen": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "Armaturentyp",
          "Baujahr",
          "Beschreibung",
          "Hersteller"
        ],
        "properties": {
          "Baujahr": {
            "type": [
              "string",
              "null"
            ],
            "description": "Baujahr"
          },
          "Hersteller": {
            "type": [
              "string",
              "null"
            ],
            "description": "Hersteller"
          },
          "Armaturentyp": {
            "enum": [
              "Absperr- und Regelarmaturen",
              "Sicherungs- und Sicherheitsarmaturen",
              null
            ],
            "type": [
              "string",
              "null"
            ],
            "description": "Armaturentyp"
          },
          "Beschreibung": {
            "type": [
              "string",
              "null"
            ],
            "description": "Beschreibung (Freitextfeld zur allgemeinen Beschreibung von Objektinformationen)"
          }
        }
      },
      "description": "422.82 Armaturen"
    },
    "Beschreibung": {
      "type": [
        "string",
        "null"
      ],
      "description": "Beschreibung (Freitextfeld zur allgemeinen Beschreibung von Objektinformationen)"
    },
    "Rohrleitungen": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "Baujahr",
          "Begleitheizung",
          "Beschreibung",
          "Material"
        ],
        "properties": {
          "Baujahr": {
            "type": [
              "string",
              "null"
            ],
            "description": "Baujahr"
          },
          "Material": {
            "enum": [
              "Grauguss",
              "Kupfer",
              "Kunststoff",
              "Glas",
              "Stahl",
              "Edelstahl (nicht rostender Stahl)",
              null
            ],
            "type": [
              "string",
              "null"
            ],
            "description": "Material"
          },
          "Beschreibung": {
            "type": [
              "string",
              "null"
            ],
            "description": "Beschreibung (Freitextfeld zur allgemeinen Beschreibung von Objektinformationen)"
          },
          "Begleitheizung": {
            "type": [
              "string",
              "null"
            ],
            "description": "Begleitheizung"
          }
        }
      },
      "description": "422.84 Rohrleitungen"
    },
    "Schmutzfaenger": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "Baujahr",
          "Beschreibung",
          "Hersteller"
        ],
        "properties": {
          "Baujahr": {
            "type": [
              "string",
              "null"
            ],
            "description": "Baujahr"
          },
          "Hersteller": {
            "type": [
              "string",
              "null"
            ],
            "description": "Hersteller"
          },
          "Beschreibung": {
            "type": [
              "string",
              "null"
            ],
            "description": "Beschreibung (Freitextfeld zur allgemeinen Beschreibung von Objektinformationen)"
          }
        }
      },
      "description": "422.83 Schmutzfänger (Schmutzfilter)"
    }
  }
}

Payload

{
  "Beschreibung": "Verteiler für Warmwasser",
  "Rohrnetz": [],
  "Pumpen": [
    {
      "Bauart": "Einpumpenanlage",
      "Baujahr": "2016",
      "Beschreibung": "Wilo Einzelpumpenanlage Comfort-N-Vario",
      "Durchfluss": "600 l/m",
      "Foerderhoehe": "10 m",
      "Hersteller": "Wilo",
      "LeistungElektrisch": null
    }
  ],
  "Armaturen": [],
  "Schmutzfaenger": [],
  "Rohrleitungen": []
}

Facility schemas can contain attributes on the first level or attributes on the second level (array of parts). For the example above we have:

• First level attributes: Beschreibung (here with the value "Verteiler für Warmwasser")
• Parts: Rohrnetz, Pumpen, Armaturen, Schmutzfaenger and Rohrleitungen. If present these parts have attributes (second level), e.g. Bauart.

Types

Types are a way to categorize entities.

For facilities the type has an effect on the validation of the type_dependent_attributes body param. The suggested workflow is as follows:

1. Fetch a list of all facility types GET /v1/facility_types and choose the appropriate one for the new or existing facility
2. Read the JSON schema of the chosen facility type GET /v1/facility_types/{facility_type_id}
3. Create or update the facility which matches the facility_type_id and the schema of the facility type with the type_dependent_attributes .

Attachments and images

The files for attachments and images are encoded as Base64 strings. You need to encode them and attach the resulting string as a body param. Each library has its own tools for this encoding, but in case you have troubles please check if you get the same results as this Online tool.

Activities

Activities can not be deleted. This is by purpose as it should not be possible to undo any activity. In case an activity was created by accident it should be archived.

Archive

It is possible to archive properties, lots, buildings, levels, rooms, zones, facilities, building units, images, attachments and activities. Archiving e.g. a property will archive recursively all underlying entities. If an entity is archived it will still appear in the results, but has a timestamp archived_at set. Use the archive functionality if you want to exclude certain portfolios for e.g. reports when they are sold and only part of the organisation for burden of proof.

Data model

This data model contains an extract of the full application data model.