REST-API

Allt webbgränssnittet gör, gör det över ett REST-API som du kan använda direkt. Den interaktiva specifikationen serveras av din egen installation på /api/, med det råa OpenAPI-dokumentet på /api/swagger.json. Det är den auktoritativa endpointlistan, och den matchar den version du faktiskt kör.

Den här sidan täcker det specifikationen inte förklarar väl: hur autentiseringen fungerar.

Autentisering är två anrop

En session skapas först och växlas sedan mot en token. Båda skickas därefter på varje följande anrop, som två separata headers.

1. Skapa en session. GET /api/auth returnerar ett sessions-id och en nonce.

   curl -s https://app.example.aiqu.ai/api/auth

   {"result":[{"nonce":1300398300,"session":"ca909fdb-…"}],"status":"success"}

2. Växla den mot en token. POST /api/auth med session, nonce och dina uppgifter.

   curl -s -X POST https://app.example.aiqu.ai/api/auth \
     -H 'Content-Type: application/json' \
     -d '{"session":"ca909fdb-…","nonce":1300398300,
          "username":"du@example.com","password":"…"}'

   {"result":[{"token":"7f6207a6…","userid":10,"validto":"…"}],"status":"success"}

3. Anropa API:t med båda värdena, som separata headers.

   curl -s https://app.example.aiqu.ai/api/user/permission \
     -H "Session: ca909fdb-…" \
     -H "Token: 7f6207a6…"

Båda headers, varje gång

Session ensam är inte autentisering och Token ensam är det inte heller. Att skicka en av två ger en 401 som ser ut som fel lösenord.

Svar

Varje svar är inslaget på samma sätt:

{ "status": "success", "result": [ … ] }

status är success eller error. Vid fel bär result meddelandet. result är oftast en lista även när den håller ett objekt, så result[0] är den normala vägen in.

Att logga ut

DELETE /api/auth med Session-headern avslutar sessionen. Tokens går också ut av sig själva - validto i inloggningssvaret säger när.

Att kontrollera vad du är

Användbart när ett skript beter sig annorlunda än personen som skrev det:

Är jag tenantadministratör?

curl -s .../api/user/permission -H "Session: …" -H "Token: …"
# {"result":[{"realmadmin":false}],"status":"success"}

Är jag superadmin?

curl -s -o /dev/null -w '%{http_code}\n' \
  .../api/superadmin/realm -H "Session: …" -H "Token: …"
# 200 för en superadmin, 401 för alla andra

Fältnamnen säger fortfarande realm

realmadmin, realmid, realmloginname och sökvägen /superadmin/realm heter så i API:t. Ordet är deprekerat i gränssnittet och i den här dokumentationen, men att byta det i API:t vore en brytande ändring och en databasmigrering.

Behörigheter gäller likadant

API:t tillämpar exakt vad gränssnittet gör. En grupp utan behörigheten att lägga jobb får ett avslag från POST /api/job precis som den får en avaktiverad knapp i formuläret. Ingenting går att nå över API:t som samma konto inte kunde nå i webbläsaren.

Endpointgrupper

Prefix	Täcker	Kräver
/auth	Sessioner, registrering, lösenordsåterställning, inbjudningar	—
/job	Att skicka in, lista, redigera, avbryta	Användare
/storage	Buckets och deras innehåll	Användare
/queue	Köer, och kopplingen kö till nod	Användare
/user	Din egen profil och dina behörigheter	Användare
/admin/…	Användare, grupper, köer, lagring, noder, projekt	Tenantadmin
/superadmin/…	Tenants, globala noder och köer, imitation	Superadmin

Läs /api/swagger.json på din egen installation för de exakta formerna. Den här tabellen är en karta, inte ett kontrakt.