Administravimo API atsakymų ir klaidų sutartis

Šis failas papildo kiekvieno Galinių taškų žinyne esančio galinio taško atsakymų sutartį. Galinio taško eilutėje skaitykite sėkmingo atsakymo turinį, o toliau pateiktose lentelėse — visą bendrą ir konkrečiam taškui būdingą nesėkmės turinį. Pagal numatymą klaidos naudoja kelias suderinamumo struktūras; kviečiančiosios programos gali pasirinkti vieną universalų apvalkalą.

Neprivalomas struktūrizuotas klaidos apvalkalas

Siųskite šią užklausos antraštę bet kuriam galiniam taškui:

X-Error-Format: envelope

Lyginant reikšmes pašalinami kraštiniai tarpai ir neskiriamos didžiosios bei mažosios raidės. Esant tiksliai šiai reikšmei, kiekvienas JSON atsakymas, kurio būsena 400 arba didesnė, konvertuojamas į:

ErrorEnvelope = {
  error: {
    code: string,
    message: string,
    details: Record<string, unknown>,
    requestId: string
  }
}

Numatytojo tikrinimo turinio konvertavimo pavyzdys:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid request",
    "details": {
      "fields": {
        "name": ["String must contain at least 1 character(s)"]
      }
    },
    "requestId": "integration-42"
  }
}

Tikslios konvertavimo taisyklės:

• validationErrors tampa details.fields, o code tampa VALIDATION_FAILED, net jei numatytajame turinyje buvo ir srities kodas.
• Kai nėra tikrinamų laukų, išlaikoma numatytoji aukščiausio lygio code reikšmė.
• Kitos aukščiausio lygio savybės, išskyrus error, message, validationErrors ir code, perkeliamos į details; pavyzdžiui, ataskaitos eksporto limit tampa details.limit.
• Aukščiausio lygio eilutės tipo error tampa message. Jei tokio nėra, naudojamas numatytasis būsenos pranešimas.
• Numatytieji kodai yra AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 ir kiti neklasifikuoti 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) ir INTERNAL_ERROR (kiti 5xx, įskaitant 503).
• requestId yra tiksli X-Request-Id atsakymo antraštė. Kviečiančiosios programos pateiktas užklausos ID naudojamas tik jei pašalinus kraštinius tarpus atitinka [A-Za-z0-9._:-]{1,128}; kitu atveju serveris sugeneruoja UUID.

Ši transformacija nekeičia būsenos ar su turiniu nesusijusių antraščių. Ji taip pat taikoma idempotentiniams pakartojimams pagal pakartojimo užklausos X-Error-Format antraštę. Dvejetainiai sėkmingi atsakymai lieka dvejetainiai; jų JSON klaidos įdedamos į apvalkalą. Likusiose lentelėse parodytas numatytasis turinys; pritaikius pirmiau pateiktas taisykles gaunamas kitas galimas kiekvienos eilutės atsakymo turinys.

Atsakymų žymėjimas

ValidationError = {
  validationErrors: Record<string, string[]>,
  code?: string
}

CodedError = {
  error: string,
  code: string,
  // a route may add fields explicitly listed below
}

PlainError = { error: string }

error ir tikrinimo pranešimo tekstas yra aprašomieji, o ne stabilus programinis skiriamasis požymis. Sprendimus grįskite code, kai jis pateiktas. Užklausos tikrinimas grąžina 422 ValidationError; viso objekto tikrinimas gali pateikti { "validationErrors": {} }, kai nenurodytas atskiras laukas. Netinkamas JSON ir netikėti sutrikimai grąžina bendrą toliau parodytą 500 PlainError.

Visi JSON pavyzdžiai rodo tikslią turinio struktūrą. Tekstas, pateiktas kaip <message>, yra grąžintas tikrinimo arba operacijos pranešimas ir yra JSON eilutė, o ne pažodinė reikšmė su kampiniais skliaustais.

Užklausų apdorojimo tvarka

Užklausos apdorojamos tokia tvarka:

1. darbo srities prieigos raktų konfigūracija ir autentifikavimas;
2. paslaugos teikėjo taisyklės ir prieigos rakto / darbo srities užklausų dažnio ribos;
3. filtravimas pagal esamas teises;
4. kiekvienai duomenų keitimo operacijai — idempotentiškumo tikrinimas / rakto rezervavimas;
5. galinio taško prieigos sričių tikrinimas, užklausos tikrinimas ir prašoma operacija.

Todėl net duomenų keitimo užklausoje su galiojančiu, bet nepakankamų prieigos sričių raktu būtina siųsti Idempotency-Key. Užbaigtą 403, 404, 409 arba 422 duomenų keitimo atsakymą galima pakartotinai gauti naudojant tą patį raktą ir užklausą.

Autentifikavimo, prieigos taisyklių ir užklausų dažnio ribojimo atsakymai

Šie atsakymai gali pasitaikyti bet kuriame registruotame /v2/admin galiniame taške prieš jam būdingą apdorojimą.

API prieiga įtraukta į visus planus. Išjungus darbo srities paslaugos teikėjo nustatymą adminApiEnabled, grąžinamas 404; praradus papildomą teisę į funkciją pašalinamos tik paveiktos prieigos sritys. Toks prieigos srities atmetimas naudoja toliau pateiktą atsakymą, o ne prieigos rakto atnaujinimo eigą.

Prieigos srities, idempotentiškumo, analizavimo, nuosavybės ir netikėti sutrikimai

Išteklių kelio ID turi būti teigiami skaičiai. Neteigiamas arba neskaitinis :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId arba :localUserId grąžina 422 ValidationError, o ne 400.

Vietų ir galios valdymo klaidos

Įkroviklių klaidos

mapChargerErrors() naudojamas įkrovikliui kurti / atnaujinti, prisijungimo duomenims, jungties nustatymams, viešam paskelbimui, QR duomenų nustatymui, konfigūracijos keitimui / įkėlimui iš naujo, programinės aparatinės įrangos naujinimui pradėti, visoms keturioms pagrindinėms komandoms ir sudėtinio tvarkaraščio užklausai.

Paprastos skaitymo operacijos grąžina tik bendrus 401/403/404/429/500/503 atsakymus ir 422 užklausos parametrų ar kelio tikrinimo atsakymą. Įkroviklio trynimas gali grąžinti bendrą 500 PlainError, jei trynimas nepavyksta be konkretesnio klaidos atsakymo.

Ataskaitų klaidos

Sėkmingas eksportas yra dvejetainis; visos eksporto klaidos lieka JSON formato.

Tarifų klaidos

Įkrovimo profilių klaidos

Naudotojo srities klaidos

Naudotojų tikrinimo klaidos, nurodančios lauką, naudoja ValidationError ir code; kitos naudotojų klaidos naudoja CodedError. Visi nerastų išteklių atvejai naudoja bendrą egzistavimo neatskleidžiantį RESOURCE_NOT_FOUND atsakymą.

POST /users/invitations taip pat gali grąžinti bendrą 403 INSUFFICIENT_SCOPE po turinio analizavimo, jei trūksta users:access, arba jei pateiktas RFID ir trūksta users:rfid. Vietinių naudotojų galiniai taškai išvardija visas būtinas prieigos sritis Galinių taškų žinyne.

Naudotojų klaidų kodai taikomi taip:

Visi šių grupių nuosavybės ir nerastų išteklių rezultatai, įskaitant neregistruotą el. pašto adresą POST /users atveju, naudoja bendrą 404 RESOURCE_NOT_FOUND turinį.

Atsakymai be turinio ir pakartojimų atsakymai

Sėkmingas 204 atsakymas neturi turinio. Tai taikoma visoms dokumentuotoms trynimo operacijoms, kurioms nurodytas 204 empty. Užbaigtas idempotentinis pakartojimas nustato Idempotency-Replayed: true ir naudoja išsaugotą būseną bei turinį; 204 atveju HTTP atsakymas vis tiek lieka be turinio. API niekada negrąžina JSON sėkmės objekto dokumentuotai 204 operacijai.