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 assets 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. |
Headers
In de headers stuur je de API-sleutel naar het 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: “https://api.calculus.group/General/PostData?api-version=2.0”.
Headers
In de headers stuur je de API-sleutel naar het 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.
|
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"
}
]
}