Administrēšanas API atbilžu un kļūdu līgums

Šis fails pabeidz atbilžu līgumu katram galapunktam Galapunktu uzziņā. Veiksmīgās atbildes saturu lasiet galapunkta rindā, bet visu kopīgo un galapunktam specifisko neveiksmīgo atbilžu saturu — tālāk norādītajās tabulās. Noklusēti kļūdas izmanto vairākas saderības struktūras; izsaucēji var izvēlēties vienu universālu ietvaru.

Neobligāts strukturēts kļūdas ietvars

Nosūtiet šo pieprasījuma galveni jebkurā galapunktā:

X-Error-Format: envelope

Vērtības salīdzināšanā tiek noņemtas sākuma un beigu atstarpes un netiek ņemts vērā burtu reģistrs. Ar šo precīzo vērtību katra JSON atbilde, kuras statuss ir 400 vai augstāks, tiek pārveidota par:

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

Noklusējuma validācijas satura pārveidošanas piemērs:

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

Pārveidošanas noteikumi ir precīzi:

• validationErrors kļūst par details.fields, un code kļūst par VALIDATION_FAILED arī tad, ja noklusējuma saturs ietvēra domēna kodu.
• Ja nav validācijas lauku, tiek saglabāts noklusējuma augstākā līmeņa code.
• Citi augstākā līmeņa rekvizīti, izņemot error, message, validationErrors un code, tiek pārvietoti uz details; piemēram, pārskata eksporta limit kļūst par details.limit.
• Virknes tipa augstākā līmeņa error kļūst par message. Ja tāda nav, tiek izmantota statusa rezerves vērtība.
• Rezerves kodi ir AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 un citi neklasificēti 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) un INTERNAL_ERROR (citi 5xx, tostarp 503).
• requestId ir precīzā X-Request-Id atbildes galvene. Izsaucēja norādīts pieprasījuma ID tiek izmantots tikai tad, ja pēc sākuma un beigu atstarpju noņemšanas tas atbilst [A-Za-z0-9._:-]{1,128}; citādi serveris ģenerē UUID.

Šī pārveidošana nemaina statusu vai galvenes, kas nav saistītas ar saturu. Tā attiecas arī uz idempotentiem atkārtojumiem atbilstoši atkārtojuma pieprasījuma X-Error-Format galvenei. Veiksmīgas binārās atbildes paliek bināras; to JSON kļūdas tiek ievietotas ietvarā. Atlikušās tabulas rāda noklusējuma saturu; piemērojot iepriekš norādītos noteikumus, iegūst otru iespējamo katras rindas atbildes saturu.

Atbilžu apzīmējumi

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

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

PlainError = { error: string }

error un validācijas ziņojuma teksts ir aprakstošs, nevis stabils programmatisks atšķiršanas kritērijs. Ja ir code, atšķiriet gadījumus pēc tā. Pieprasījuma validācija atgriež 422 ValidationError; visa objekta validācija var radīt { "validationErrors": {} }, ja nav identificēts atsevišķs lauks. Nederīgs JSON un neparedzētas kļūmes atgriež tālāk norādīto globālo 500 PlainError.

Visi JSON piemēri rāda precīzu satura struktūru. Teksts, kas parādīts kā <message>, ir atgrieztais validācijas vai darbības ziņojums un ir JSON virkne, nevis burtiska vērtība leņķiekavās.

Pieprasījumu apstrādes secība

Pieprasījumi tiek apstrādāti šādā secībā:

1. darbvietas marķieru konfigurācija un autentifikācija;
2. saimnieka politika un marķieru/darbvietu biežuma ierobežojumi;
3. pašreizējo tiesību filtrēšana;
4. katrai izmaiņai — idempotences validācija/rezervācija;
5. galapunkta tvērumu pārbaudes, pieprasījuma validācija un pieprasītā darbība.

Tādēļ arī izmaiņu pieprasījumam ar derīgu, bet nepietiekama tvēruma marķieri ir jāsūta Idempotency-Key. Pabeigtas 403, 404, 409 vai 422 izmaiņas atbildi var atkārtot tai pašai atslēgai/pieprasījumam.

Autentifikācijas, politikas un biežuma ierobežojumu atbildes

Šīs atbildes var rasties katrā reģistrētajā /v2/admin galapunktā pirms galapunktam specifiskās apstrādes.

API piekļuve ir iekļauta katrā plānā. Atspējojot darbvietas saimnieka adminApiEnabled iestatījumu, tiek atgriezts 404; zaudējot papildu funkcijas tiesības, tiek noņemti tikai attiecīgie tvērumi. Iegūtais tvēruma atteikums izmanto tālāk norādīto atbildi, nevis marķiera atsvaidzināšanas plūsmu.

Tvēruma, idempotences, parsēšanas, īpašumtiesību un neparedzētas kļūmes

Resursu ceļu ID jābūt pozitīviem skaitļiem. Nepozitīvs vai neskaitlisks :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId vai :localUserId atgriež 422 ValidationError, nevis 400.

Objektu un jaudas pārvaldības kļūdas

Lādētāju kļūdas

mapChargerErrors() izmanto lādētāja izveide/atjaunināšana, piekļuves dati, pieslēgvietu iestatījumi, publiskais saraksts, QR satura noteikšana, konfigurācijas maiņa/pārlāde, aparātprogrammatūras sākšana, visas četras pamata komandas un apvienotā grafika pieprasījums.

Vienkāršas lasīšanas darbības atgriež tikai kopīgās 401/403/404/429/500/503 atbildes un 422 vaicājuma/ceļa validāciju. Lādētāja dzēšana var atgriezt kopīgo 500 PlainError, ja dzēšana neizdodas bez konkrētākas kļūdas atbildes.

Pārskatu kļūdas

Veiksmīgais eksports ir binārs; visas eksporta kļūdas paliek JSON.

Tarifu kļūdas

Uzlādes profilu kļūdas

Lietotāju domēna kļūdas

Lietotāja validācijas kļūdas, kas identificē lauku, izmanto ValidationError un code; citas lietotāju kļūdas izmanto CodedError. Visi trūkstoša resursa gadījumi izmanto kopīgo resursu uzskaitīšanu nepieļaujošo RESOURCE_NOT_FOUND atbildi.

POST /users/invitations var arī atgriezt kopīgo 403 INSUFFICIENT_SCOPE pēc satura parsēšanas, ja trūkst users:access, vai ja ir norādīts RFID un trūkst users:rfid. Vietējo lietotāju galapunkti uzskaita katru nepieciešamo tvērumu Galapunktu uzziņā.

Lietotāju kļūdu kodi tiek piemēroti šādi:

Visi īpašumtiesību un trūkstošu resursu rezultāti šajās grupās, tostarp nereģistrēta e-pasta adrese galapunktā POST /users, izmanto kopīgo 404 RESOURCE_NOT_FOUND saturu.

Atbildes bez satura un atkārtojumi

Veiksmīgai 204 atbildei nav satura. Tas attiecas uz katru dokumentēto dzēšanu, kur norādīts 204 empty. Pabeigta idempotenta atkārtošana iestata Idempotency-Replayed: true un izmanto saglabāto statusu/saturu; 204 gadījumā HTTP atbilde joprojām ir bez satura. Dokumentētai 204 darbībai API nekad neatgriež JSON veiksmes objektu.