Introduktion

VIGTIGT
API'et er stadig i beta og kan indeholde fejl - det anbefales ikke du åbner for API'et ud imod internettet med mindre du har opsat SSL kryptering.

Hvis du ønsker at få dit API ud på det åbne internet anbefaler jeg at du enten benytter IHC Captain styrdithus.dk servicen eller du opsætter LetsEncrypt og dermed kører alting via https, f.eks. https://pimylifeup.com/raspberry-pi-ssl-lets-encrypt/

I dokumentationen omtales der ressourcer som i denne sammenhæng kan være både input, outputs, ugedag, dato og alt hvad der elers kan indsættes i en IHC functionsblok

Det anbefales at bruge Token baseret authentication, og det anbefales også at bruge POST kald til at sætte værdier og GET til at hente værdier.

API opsætning

Api'et konfigureres under Kontrolpanel fanen API

API adgang

Du kan under API adgang frakoble API'et eller tilkoble de forskellige måder at forbinde imod API'et på.

API'et understøtter Basic Auth eller Token based - der er begge muligheder for at det skal være nemt at lave intergration med fleste mulige forskellige løsninger. Derfor kan man også både POST og GET for at sætte en værdi.

API bruger

Med API bruger kan du vælge hvilken IHC Captain bruger API'et skal handle på vegne af. Du kan vælge mellem de brugere du har oprettet i IHC Captain og derudover en specielt til API'et, IHCCapAPI. Som standard anbefales IHCCapAPI brugeren som kan påvirke alt og ikke kan slettes etc.

Du kan dog vælge en anden bruger hvis du ønsker at begrænse hvilke rettigheder api'et har, det følger så den valgte brugers rettigheder.

Bemærk at den valge API Bruger også er det brugernavn du skal benytte ved Basic Auth adgang

Basic Auth

Benyttes dette kan du her indtaste eller generere en adgangskode til basic auth. Brugernavnet til Basic Auth er "API Bruger"

Header token

Benyttes dette kan du her indtaste eller generere en token

Nem API beskrivelse

Skal du bare hurtigt hente eller sætte en ressource i IHC Captain via API'et kan IHC Captain lave "koden" for dig ved at du trykker på -knappen så den er grøn/aktiv

Find herefter den ressource du vil hente eller sætte - tryk på "+ Handling" knappen

Vælg fanen API - herfra kan du så vælge hvad du vil have api'et til at gøre - enten hente eller sætte en værdi.

Du kan også vælge om du vil hente/sætte den initielle værdi - hvis du er i tvivl skal du ikke bruge initiel værdi :)

Hvis du vil sætte værdien kan det vælges vha. dropdown menu

Nederst kan du få eksempler på hvordan du laver kaldet vha. f.eks. Curl eller wget

IHC ressourcer/datatyper

Lige en kort introduktion til IHC/LKs ressource/datatyper... Der findes en række forskellige datatyper og formatet på nogen af dem kan være lidt svært for intergrationen så derfor har jeg lavet en oversigt over de primære - suppleret med hvilke måde de kan læses og sættes. Bemærk min og max værdier er IKKE de tekniske begrænsninger men den måde de er "begrænset" på i IHC løsningen.

For at finde det unikke ID som skal bruges til at hente eller sætte et IHC ressource id kan man i IHC Captain brugerfladen trykke på en ressource samtidig med man holder CTRL-knappen nede - så vil id'et blive vist.

API'et har en "convertedValue" som der er måde at ensrette output så det passer med det brugerfladerne normalt viser - på samme måde tillader api'et også man kan sætte værdierne mere "simpelt" ved ikke at sende et komplet objekt men f.eks. blot en dato streng - se altSetValues.

Oversigt

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "value": "boolean"
}

{
    "value": "false"
}

{
    "floatingPointValue": "double"
}

{
    "floatingPointValue": 33,
    "maximumValue": "100",
    "minimumValue": "-100"
}

{
    "floatingPointValue": "double"
}

{
    "floatingPointValue": 33,
    "maximumValue": "100",
    "minimumValue": "0"
}

{
    "floatingPointValue": "double"
}

{
    "floatingPointValue": 33,
    "maximumValue": "100000",
    "minimumValue": "-100000"
}

{
    "floatingPointValue": "double"
}

{
    "floatingPointValue": 33,
    "maximumValue": "10000000",
    "minimumValue": "0"
}

{
    "floatingPointValue": "double"
}

{
    "floatingPointValue": 33,
    "maximumValue": "10000000",
    "minimumValue": "0"
}

{
    "floatingPointValue": "double"
}

{
    "floatingPointValue": 33,
    "maximumValue": "10000000",
    "minimumValue": "0"
}

{
    "floatingPointValue": "double"
}

{
    "floatingPointValue": 33,
    "maximumValue": "10000000",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "60000",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "100",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "32767",
    "minimumValue": "-32768"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "32767",
    "minimumValue": "-32768"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "100",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "99999999",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "99999999",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "99999999",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "99999999",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "99999999",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "99999999",
    "minimumValue": "0"
}

{
    "integer": "int"
}

{
    "integer": 50,
    "maximumValue": "99999999",
    "minimumValue": "0"
}

{
    "day": "byte",
    "month": "byte",
    "year": "short"
}

{
    "year": 2000,
    "month": 1,
    "day": 28
}

{
    "hours": "int",
    "minutes": "int",
    "seconds": "int"
}

{
    "hours": 2,
    "seconds": 59,
    "minutes": 57
}

{
    "weekdayNumber": "long"
}

{
    "weekdayNumber": 0
}

{
    "milliseconds": "long"
}

{
    "milliseconds": 82739000
}

{
    "milliseconds": "long"
}

{
    "milliseconds": 82739000
}

{
    "definitionTypeID": "int",
    "enumValueID": "int",
    "enumName": "string"
}

{
    "definitionTypeID": 5429831,
    "enumValueID": 5430088,
    "enumName": "En Enum v\u00e6rdi"
}

Teknisk dokumentation

Generiske parametre

Til alle nuværende API endpoints findes der følgende parametre som altid kan sættes

action

Hvilke handling skal API'et udføre. Kan være getValues eller setValues - som henholdsvis enten bruges til at hente eller sætte værdier.

initial

Hvis sat til true så hentes/sættes så den initiale værdi istedet for den aktuelle værdi. Bruges normalt ikke. Standard er false

id/ids

Angiver hvilke id'er/ressourcer der skal hentes/sættes - kan angives i enten decimaltal (f.eks. 191579) eller hexadecimal (f.eks. _0x2ec5b, 0x2ec5b, 2ec5b). Du kan i IHC Captain brugerfladen trykke på en ressource samtidig med du holder CTRL-knappen nede - så vil id'et blive vist.

Fejltyper

501

Hvis API'et er frakoblet i kontrolpanelet

400

Hvis der mangler et eller flere parametre eller de er forkerte

401

Manglende authentication parametre

403

Ugyldig authentication

500

Intern server fejl - fejl i API backend

Fuld API beskrivelse

For at gøre API dokumentation vedligeholdelse nemmere finder du den tekniske beskrivelse her:
https://documenter.getpostman.com/view/18554375/UVR7MUsJ