Algemene methoden en responses
HTTP-methoden
- U gebruikt GET om gegevens op te halen.
- Met POST en PUT voegt u gegevens toe of overschrijft u bestaande gegevens.
- Met DELETE verwijdert u gegevens.
Alle verzoeken en antwoorden maken gebruik van JSON-objecten en arrays als gegevensformaat.
| HTTP-methode | Doel |
|---|---|
| GET | Ophalen van alle elementen van de entiteit, of één specifiek element op basis van ID. |
| POST | Maken van een nieuwe entiteit. |
| PUT | Bijwerken van een bestaand element met nieuwe gegevens. |
| DELETE | Verwijderen van een entiteit. |
De REST API is vastgelegd in het OpenAPI (Swagger) formaat. U vindt deze documentatie via de browser op het IP-adres van de Octalarm alarmmelder, gevolgd door /rest_api/1/. Bijvoorbeeld:
http://192.168.10.72/rest_api/1/
Het onderdeel /1/ in de URL is het versienummer van de REST API. Zolang uitbreidingen compatibel blijven, blijft dit nummer gelijk. Niet-compatibele uitbreidingen komen onder een nieuw versienummer.
Goed om te weten: via deze URL:
- vindt u een overzicht van alle API's, inclusief documentatie;
- kunt u de API's uitvoeren of testen;
- vindt u bij elke API het bijbehorende cURL-commando. cURL is een opdrachtregeltool om gegevens op te vragen of te versturen; u gebruikt deze tool om met de REST API te communiceren.
Authenticatie
De REST API gebruikt een Bearer-token voor authenticatie. U stuurt dit token als HTTP-header mee 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 vindt u op jwt.io.
Responses
Octalarm Link geeft bij een REST API-aanvraag verschillende HTTP-statuscodes terug. Afhankelijk van de response kunt u het verzoek (na een korte pauze) eventueel opnieuw doen.
Let op: herhaal een POST voor een alarmmelding altijd periodiek (bijvoorbeeld iedere minuut), ongeacht de ontvangen HTTP-statuscode.
2XX
U krijgt deze code bij een succesvol verzoek.
- 200 OK: het verzoek is geslaagd.
4XX
Deze codes geven aan dat het verzoek is mislukt, en dat het niet zinvol is om exact hetzelfde verzoek opnieuw in te dienen.
Let op: gaat uw verzoek om een alarmmelding? Dan moet u deze altijd periodiek blijven herhalen, ook als het hetzelfde verzoek betreft.
- 400 Bad Request: algemene foutstatus, bijvoorbeeld door het bereiken van een limiet (zoals het maximum aantal actieve alarmen) of onjuiste gegevens.
- 401 Unauthorized: het verzoek bevat geen geldige authenticatiegegevens.
- 403 Forbidden: het verzoek is correct, maar de REST API weigert de actie te autoriseren.
- 404 Not Found: de gevraagde bron bestaat niet.
- 405 Method Not Allowed: u gebruikt een HTTP-methode die voor deze bron niet is toegestaan.
5XX
Bij een 5XX-code was er een fout op de serverzijde. Meestal heeft het geen zin om exact hetzelfde verzoek opnieuw te doen.
Let op: gaat uw verzoek om een alarmmelding? Dan moet u deze altijd periodiek blijven herhalen, ook als het hetzelfde verzoek betreft.
- 500 Internal Server Error: hierdoor is het verzoek niet verwerkt. Dit is de algemene foutmelding van de REST API. U kunt dit verzoek na een korte pauze opnieuw indienen.