Algemene methoden en responsen

HTTP methoden

Net als bij elke REST API gebruikt u:

• GET verzoeken om gegevens op te halen;
• POST en PUT verzoeken om gegevens toe te voegen of te overschrijven;
• DELETE om gegevens te verwijderen.

Alle verzoeken en antwoorden gebruiken JSON objecten en arrays als gegevensformaat.

De REST API is gedocumenteerd in het OpenAPI (Swagger) formaat. Deze is op te vragen in een browser op het IP-adres van de Octalarm alarmmelder gevolgd door /rest_api/1/. Bijvoorbeeld:

http://192.168.10.72/rest_api/1/

De /1/ in de URL is het versienummer van de REST API. Zolang de REST API aanvragen in de toekomst compatibel uitgebreid worden, blijft dit versienummer ongewijzigd. Incompatibel uitbreidingen worden toegevoegd aan een nieuw versienummer.

Goed om te weten: via deze URL
1. vindt u een overzicht van alle API's, inclusief documentatie;
2. is het mogelijk de API's uit te voeren of te testen;
3. vindt u bij elke API het cURL commando. cURL is een command-line tool voor het verkrijgen of verzenden van data en kan gebruikt worden om te communiceren met de REST API.

Authenticatie

De REST API maakt gebruik van een token (type Bearer) om de REST API koppeling te verifiëren. Het externe apparaat zendt het token mee als HTTP header bij elke API aanvraag.

Voorbeeld:

GET /rest_api/1/Interface/RestApiLimits HTTP/1.1
Host: 192.168.10.72
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTY2OTg5MDk2NiwianRpIjoiMDUyMzJmZjAtZjJjZC00NTdlLTlmYTUtOGExMjY1OTY2NjQxIiwibmJmIjoxNjY5ODkwOTY2LCJ0eXBlIjoicmVmcmVzaCIsInN1YiI6IlJFU1QtQVBJXzAwMDUiLCJ1c2VyX2lkIjo3LCJyb2xlX2lkIjo1LCJsYW5ndWFnZSI6Im5sLU5MIn0.hp9hictrwsLW5W2G3XFKPMqChf0_0oXxcSoWGpmZF-A

Goed om te weten: meer informatie over tokens staat op jwt.io.

Responsen

Octalarm Link kan een REST API aanvraag met diverse HTTP response codes beatwoorden. Afhankelijk van de HTTP response is het zinvol om de aanvraag (na een korte pauze) opnieuw te proberen wanneer deze niet is gelukt.

Let op: een POST van een alarm moet u altijd periodiek herhalen (bijvoorbeeld elke minuut), ongeacht welke HTTP response code u terugkrijgt.

2XX

Deze groep responses geeft aan dat het verzoek is geslaagd.

• 200 OK: verzoek is geslaagd.

4XX

Deze groep responses geeft aan dat het verzoek is mislukt en het geen zin heeft om exact hetzelfde verzoek nog een keer te doen.

Let op: als het gaat om een verzoek voor een alarm moet u deze altijd periodiek blijven herhalen; ook als het exact hetzelfde verzoek is.

• 400 Bad Request: algemene foutstatus. Wordt gebruikt wanneer er geen specifieke foutcode is die beter past of wanneer een limiet is bereikt, bijvoorbeeld een maximum aantal actieve alarmen.

• 401 Unauthorized: het verzoek is niet toegepast omdat geldige authenticatiegegevens voor de doelbron ontbreken.

• 403 Forbidden: het verzoek van de client is correct gevormd, maar de REST API weigert het te autoriseren.

• 404 Not Found: de aangevraagde bron is niet gevonden.

• 405 Method Not Allowed: de client heeft geprobeerd een HTTP-methode te gebruiken die de bron niet toestaat.

5XX

Bij deze groep responsen heeft het meestal geen zin om hetzelfde verzoek nog een keer te doen.

Let op: als het gaat om een verzoek voor een alarm moet u deze altijd periodiek blijven herhalen; ook als het exact hetzelfde verzoek is.

• 500 Internal Server Error: er was een fout op de server waardoor het verzoek niet is voltooid. Dit is de algemene REST API foutmelding. Bij een 500 server fout heeft het zin om het verzoek na een korte pauze opnieuw te doen.