Plattformens API
Var plattformens HTTP-API finns, hur dess rutter är ordnade och hur du listar de rutter som en installation erbjuder.
Allt som portalen och CLI:t stsh gör går via ett HTTP-API, på https://api.example.com. Du kan anropa
det själv — från skript, pipelines eller egna verktyg — med samma behörigheter som du har i
portalen.
En adress för alla moduler
API:et serveras från roten av sin värd; det finns inget prefix /api och ingen versionsdel i
sökvägen. Plattformens kärna besvarar sina egna rutter och skickar varje annat anrop, oförändrat,
vidare till den installerade modul som registrerade rutten. Vilka rutter du kan anropa beror därför
på vilka moduler din installation har.
När en modul är installerad men inte kör svarar dess rutter 503 med koden MODULE_UNAVAILABLE;
försök igen om en stund. Ett 503 med en annan kod har en annan orsak, och koden avgör om ett nytt
försök hjälper — se Fel.
Hur rutterna är ordnade
Rutterna följer de omfattningar som behörigheter ges på:
| Omfattning | Ruttprefix |
|---|---|
| Plattform | ingen boundary i sökvägen, till exempel /clusters |
| Boundary | /boundaries/{boundaryId}/… |
| Resursgrupp | /boundaries/{boundaryId}/resourcegroups/{resourceGroupName}/… |
| Resurs | /boundaries/{boundaryId}/resourcegroups/{resourceGroupName}/resources/{type}/{name} |
Varje anrop kontrolleras mot dina roller med den omfattning som sökvägen anger. När en rutt utan boundary i sökvägen kräver en behörighet kontrolleras den på plattformens rot, där bara plattformsroller gäller.
Lista rutterna
Tre slutpunkter beskriver API:et. Ingen av dem kräver inloggning.
| Slutpunkt | Vad du får |
|---|---|
https://api.example.com/api/routes |
Alla rutter i kärnan och i varje installerad modul: sökvägsmönster, metoder och modulen som betjänar dem |
https://api.example.com/api/routes/openapi.json |
Samma lista som ett OpenAPI-dokument — bara sökvägar och metoder, utan parametrar, anropskroppar eller svarsscheman |
https://api.example.com/swagger |
En interaktiv referens. Den beskriver kärnans egna slutpunkter och innehåller ruttlistan ovan |
/swagger är påslaget om inte en operatör har slagit av det (Swagger__Enabled=false); de två
ruttlistorna finns alltid.
Anropa API:et
Varje anrop som läser eller ändrar plattformens tillstånd kräver en bearer-token — se Autentisera. Anrop och svar är JSON. När ett anrop misslyckas innehåller svaret en felkropp som beskrivs i Fel.
Arbete som tar en stund — att skapa, ändra eller radera en resurs — registreras som en operation som du kan följa; se Operationer.
Med CLI:t inloggat anropar stsh api vilken rutt som helst med dina autentiseringsuppgifter:
stsh api GET /boundaries
stsh api GET /boundaries/<boundary-id>/resourcegroups-d '<json>' eller -d @file.json skickar en anropskropp.
Portalen tar också emot uppdateringar i realtid via WebSocket-anslutningar under /hubs. De är ett
internt gränssnitt för portalen och kan ändras utan förvarning; fråga API:et i stället.