Hoe onze API te gebruiken

1

.

Wat is een API?

De term API staat voor Application Programming Interface. Het is een communicatieprotocol, bedoeld om de uitwisseling van gegevens tussen een client en een server te vereenvoudigen. De communicatie zal in een strict formaat verlopen, of een bepaalde actie initiëren, zodat zij elkaar perfect aanvullen.

Een API-sleutel is een unieke identificatie die wordt gebruikt voor de authenticatie van een gebruiker of een programma dat een beroep doet op de API.

2

.

Wat betekent de API voor gebruikers van ons platform?

Dit betekent dat u de API kunt gebruiken om gemakkelijk gegevens naar ons platform te sturen, of ervan op te vragen.

Stuur uw eigen gegevens om ze te combineren met de gegevens die al op ons platform staan. Dit kunnen gegevens zijn uit een ERP- of CRM-systeem, of uit sensoren en meetsystemen. U kunt ook gegevens opvragen om in uw eigen toepassing te gebruiken.

3

.

Hoe gebruik je onze API en API-sleutel?

1. Een API-sleutel aanmaken

Aangezien de API zich in een openbare beta bevindt, moet de API-sleutel worden aangevraagd via e-mail op help@calculus.group. U kunt contact met ons opnemen door een e-mail te sturen, met als onderwerp “Aanvraag API-sleutel voor Calculus“. Laat ons in de mail weten voor welk bedrijf je de API-sleutel nodig hebt en waar je hem voor gaat gebruiken.

Let op! Als de API-sleutel in gevaar zou komen, kunt u ons op hetzelfde adres een e-mail sturen om de sleutel in te trekken.

2. Gebruik de API om gegevens te verkrijgen

Met behulp van de API kunt u gegevens opvragen van alle activa die gekoppeld zijn aan het bedrijf waartoe de API-sleutel behoort. Het API-eindpunt om gegevens op te vragen is “https://api.calculus.group/asset/{key}”. Vervang {key} door de unieke identificatie van het asset. De oproepen worden gedaan met de HTTP-actie “GET”.

Parameters

epochStart


Het begin van de tijdreeks waarvan u gegevens nodig hebt.

Het gebruikte date/time formaat is “Epoch”, de UNIX tijdcode. Ga naar https://www.epochconverter.com/ voor conversiehulpmiddelen van en naar Epoch.

Indien u deze parameter gebruikt, moet dit steeds samen met de parameter “epochEnd”.

Indien niet gebruikt, is de standaard de laatste 24 uur.

epochEnd



Het einde van de tijdreeks waarvan u gegevens nodig hebt.

Het gebruikte date/time formaat is “Epoch”, de UNIX tijdcode. Ga naar https://www.epochconverter.com/ voor conversiehulpmiddelen van en naar Epoch.

Indien u deze parameter gebruikt, moet dit steeds samen met de parameter “epochEnd”.

Indien niet gebruikt, is de standaard de laatste 24 uur.


Kopteksten

In de headers stuur je de API-sleutel naar de Calculus platform om uw toestel te authenticeren.

CalculusApiKey

Gebruik de API-sleutel die u in stap 1 kreeg om u te authenticeren bij de API.


JSON-Model

De kern van het verzoek is steeds in JSON-formaat.

3. Gebruik de API om gegevens te posten

Het API eindpunt voor het posten van gegevens naar ons platform is “https://api.calculus.group/General/PostData”. De oproepen worden gedaan met de HTTP-actie “POST”.

Parameters

api-versie


De versie van de API die je wilt aanroepen. Versie 1.0 is verouderd, versie 2.0 is momenteel de aangewezen manier. Gebruik “api-version=2.0”.

Een typische oproep zou een POST zijn naar: “https://api.calculus.group/General/PostData?api-version=2.0”.

Kopteksten

In de headers stuur je de API-sleutel naar de Calculus platform om uw toestel te authenticeren.

CalculusApiKey

Gebruik de API-sleutel die u in stap 1 kreeg om u te authenticeren bij de API.

4

.

JSON-Model

De kern van het verzoek is steeds in JSON-formaat. Het gebruik van “check-deltas” en “reset-deltas” wordt gebruikt wanneer waarden kunnen overlopen en teruggezet worden naar 0. Als u de juiste cumulatieve waarden wilt, kan dit worden gebruikt om deze in onze backend te berekenen. Neem contact met ons op voor meer informatie over hoe u dit kunt implementeren op help@calculus.group.

De volgende waarden kunnen worden ingesteld:

device

Apparaatnaam van de gateway waaraan u gegevens wilt toevoegen. Als deze niet bestaat, wordt de gateway automatisch toegevoegd. Gebruik het voorvoegsel dat wij u samen met de API-sleutel voor het door u gekozen apparaat verstrekken, in het volgende formaat:

“prefix_gateway”.

timestamp

Seconden sinds 1 januari 1970 (epoch).

check-deltas

Momenteel alleen beschikbaar na het markeren van een meetpad als delta. Neem contact met ons op voor meer informatie op help@calculus.group.

reset-deltas

Momenteel alleen beschikbaar na het markeren van een meetpad als delta. Neem contact met ons op voor meer informatie op help@calculus.group.

measurements

Een array van meetwaarden die u wilt toevoegen. Dit kan een waarde hebben, een stringwaarde of beide.

path

Datatype “string”, de meetnaam. Dit zal samen met de apparaatnaam worden gebruikt om het volledige meetpad te vormen. Bijvoorbeeld met een apparaatnaam van “prefix_TestDevice” en een pad van “Testpath” zal het volledige meetpad “prefix_TestDevice|Testpath”. Behalve “.”, “_”, “-” en “|” zijn geen spaties of speciale tekens toegestaan.

value

Datatype “double”, waarde gerelateerd aan het pad.

stringValue

Datatype “string”, maximaal 50 tekens, waarde met betrekking tot het pad.

Voorbeeld JSON body

{

    "device":"prefix_TestDevice",

    "check-deltas": true,

    "reset-deltas": true,

    "timestamp":1573206752,

    "measurements":

        [

            {

                "path": "measurement_1",

                "value": 1

            },

            {

                "path": "measurement-2",

                "stringValue": "OFF"

            },

            {

                "path": "temp|measurement.3",

                "value": 9.4,

                "stringValue": "BROKEN"

            },

            {

                "path": "temp|measurement.4",

                "value": 11.4,

                "stringValue": "OVERLOAD"

            }

        ]

}

Ondersteuning nodig?

Kunt u het antwoord dat u zoekt niet vinden? Maak je geen zorgen, we zijn hier om te helpen.

Vraag om hulp