Ga naar inhoud
HD ServicesHDDeploy Help

De REST API

Voor scripts en CI-pipelines heeft uw server een REST API met dezelfde rechten en dezelfde vastlegging als het portaal.
Basisadres https://<uw-server>.hddeploy3000.nl/api/v1
Beschrijving OpenAPI 3.1 op /api/v1/openapi.json, zonder token op te vragen
Aanmelden header Authorization: Bearer hdd_... (zie API-tokens en scopes)
Fouten application/problem+json met een leesbare detail
Limiet 120 verzoeken per minuut per token (uploads uitgezonderd); daarboven 429

Werkwijze

Section titled “Werkwijze”

Lange acties geven een taak. Een deploy, stop of back-up antwoordt met 202 Accepted en een taak-id. Wacht erop met GET /jobs/{id}/wait?timeout=120; het antwoord bevat de status en de uitvoer. Is done nog niet waar, roep dan opnieuw aan.

Schrijfacties sturen de revisie mee. Wie het compose-bestand, de variabelen of de instellingen wijzigt, stuurt het revisienummer mee waarop de wijziging is gebaseerd: header If-Match: "7" (met aanhalingstekens) of het veld revision in de body. Is de stack intussen gewijzigd, dan volgt 412 Precondition Failed: lees de stack opnieuw en probeer het nog eens.

Een geweigerd compose-bestand geeft 422. Het antwoord bevat per gebroken platformregel een eigen regel in errors[]. Zie Compose-bestanden en platformregels.

Een ontbrekende scope geeft 403, een verkeerd of verlopen token 401.

Eindpunten

Section titled “Eindpunten”
Methode en pad Doet
GET /me Wie u bent en welke scopes het token heeft
GET /overview Aandachtspunten en samenvatting
GET /stacks, GET /stacks/{name} Stacks en één stack
GET/PUT /stacks/{name}/compose Het compose-bestand lezen en vervangen
POST /stacks/{name}/validate Een compose-bestand controleren zonder op te slaan
GET/PUT /stacks/{name}/env De variabelen lezen en wijzigen
PUT /stacks/{name}/settings De sjablooninstellingen wijzigen
POST /stacks/{name}/deploy, .../stop, .../pull Uitrollen, stoppen, images ophalen (202 + taak)
PUT /stacks/{name}/autoupdate Nachtelijke update aan of uit
GET /stacks/{name}/revisions, GET .../revisions/{id}, POST .../revisions/{id}/restore Revisies lezen en terugzetten
GET/PUT /stacks/{name}/source, POST .../source/check, .../pin, .../unpin De git-bron
PUT /stacks/{name}/source/upload De broncode als archief uploaden (zie Bestanden uploaden)
GET/POST /stacks/{name}/access De toegangslijst
POST/DELETE /stacks/{name}/webhooks/deploy De deploy-webhook aanzetten, vernieuwen of uitzetten
GET /containers, POST /containers/{id}/start, .../stop, .../restart, GET .../logs Containers
GET /jobs, GET /jobs/{id}, GET /jobs/{id}/wait Taken
GET /sites, GET /sites/{name}, PUT /sites/{name} Sites; PUT maakt een upload-only site
POST /sites/{name}/check, POST /sites/{name}/restore Bron controleren, vorige versie terugzetten
PUT /sites/{name}/content Een archief uploaden
GET/PUT /sites/{name}/draft/files, POST .../draft/publish, DELETE .../draft Het concept
GET /sites/{name}/files, GET /sites/{name}/file?path= Bestanden lezen
GET /backups, GET /backups/{name}/files, POST /backups/{name}/run Back-ups
GET /alerts, GET/POST /alerts/channels, DELETE /alerts/channels/{id}, POST /alerts/test Meldingen
GET /certificates, POST /certificates/request, POST /certificates/upload, DELETE /certificates/{name} Certificaten
GET/POST /registries, DELETE /registries/{host} Registry-logins

De exacte velden van elk verzoek en antwoord staan in het OpenAPI-document; de meeste API-tools (Postman, Bruno, de OpenAPI-generators) lezen het rechtstreeks in.

Voorbeelden

Section titled “Voorbeelden”
Terminal window
# Wie ben ik?
curl -H "Authorization: Bearer hdd_..." \
     https://<uw-server>.hddeploy3000.nl/api/v1/me


# Een stack uitrollen en op de taak wachten
curl -X POST -H "Authorization: Bearer hdd_..." \
     https://<uw-server>.hddeploy3000.nl/api/v1/stacks/mijnapp/deploy
curl -H "Authorization: Bearer hdd_..." \
     "https://<uw-server>.hddeploy3000.nl/api/v1/jobs/j-.../wait?timeout=120"


# Variabelen wijzigen, gebaseerd op revisie 7
curl -X PUT -H "Authorization: Bearer hdd_..." -H 'If-Match: "7"' \
     -H "Content-Type: application/json" \
     -d '{"values": {"PHP_MEMORY_LIMIT": "512M"}}' \
     https://<uw-server>.hddeploy3000.nl/api/v1/stacks/mijnapp/env


# Een compose-bestand controleren zonder op te slaan
curl -X POST -H "Authorization: Bearer hdd_..." \
     -H "Content-Type: application/json" \
     -d '{"content": "services:\n  web:\n    image: nginx:stable\n"}' \
     https://<uw-server>.hddeploy3000.nl/api/v1/stacks/mijnapp/validate

Webhooks zijn iets anders

Section titled “Webhooks zijn iets anders”

De API hierboven werkt met uw persoonlijke token en kan alles wat u kunt. Voor een CI-pipeline die alleen hoeft uit te rollen of een site te laten synchroniseren, zijn er aparte webhooks met een eigen token dat precies één handeling op één stack of site toestaat.