Admin API vastuste ja vigade leping

See fail täiendab iga Endpointide viite endpointi vastuselepingut. Eduka sisu kohta lugege endpointi rida ning kõigi ühiste või endpointipõhiste ebaedukate sisude kohta allolevaid tabeleid. Vaikimisi kasutavad vead mitut ühilduvuskuju; kliendid saavad valida ühe universaalse ümbrise.

Valikuline struktureeritud veaümbris

Saatke see päringupäis mis tahes endpointile:

X-Error-Format: envelope

Väärtuse võrdlemisel eemaldatakse ääretühikud ja tähesuurust ei arvestata. Selle täpse väärtusega teisendatakse iga JSON-vastus olekuga 400 või kõrgem kujule:

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

Vaikimisi valideerimissisu teisenduse näide:

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

Teisendusreeglid on täpsed:

• validationErrors muutub details.fields-ks ja code VALIDATION_FAILED-ks ka siis, kui vaikimisi sisul oli domeenikood.
• Vaikimisi ülataseme code säilib, kui valideerimisvälju pole.
• Muud ülataseme omadused peale error, message, validationErrors ja code liiguvad details alla; näiteks aruandeekspordi limit muutub väärtuseks details.limit.
• Ülataseme string error muutub väärtuseks message. Selle puudumisel kasutatakse oleku varuväärtust.
• Varukoodid on AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 ja muud liigitamata 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) ja INTERNAL_ERROR (muud 5xx, sealhulgas 503).
• requestId on täpne X-Request-Id vastusepäis. Kliendi antud päringu ID-d kasutatakse ainult siis, kui see vastab pärast ääretühikute eemaldamist [A-Za-z0-9._:-]{1,128}-le; muidu loob server UUID.

See teisendus ei muuda olekut ega sisuga mitteseotud päiseid. See kehtib ka idempotentsetele kordustele vastavalt korduspäringu X-Error-Format päisele. Kahendvormingus edukad vastused jäävad kahendvormingusse; nende JSON-vead saavad ümbrise. Ülejäänud tabelid näitavad vaikimisi sisu; ülaltoodud reeglid annavad igale reale teise võimaliku vastusesisu.

Vastuste tähistus

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

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

PlainError = { error: string }

error ja valideerimissõnumi tekst on kirjeldavad, mitte stabiilne programmiline eristaja. Harunege code alusel, kui see on olemas. Päringu valideerimine tagastab 422 ValidationError; kogu objekti valideerimine võib anda { "validationErrors": {} }, kui üksikut välja ei tuvastata. Vigane JSON ja ootamatud tõrked tagastavad allpool näidatud globaalse 500 PlainError.

Kõik JSON-näited on täpsed sisustruktuurid. <message> tähistab tagastatavat valideerimis- või toimingusõnumit ja on JSON-string, mitte sõnasõnaline nurksulgudes väärtus.

Päringu töötlemisjärjekord

Päringuid töödeldakse selles järjekorras:

1. tööruumi pääsutõendi seadistus ja autentimine;
2. hosti reeglistik ning pääsutõendi/tööruumi päringupiirangud;
3. praeguste õiguste filtreerimine;
4. iga muudatuse puhul idempotentsuse kontroll/hõive;
5. endpointi ulatusekontrollid, päringu valideerimine ja taotletud toiming.

Seega peab ka kehtiva, kuid ebapiisava ulatusega pääsutõendiga muudatus saatma Idempotency-Key. Lõpetatud 403, 404, 409 või 422 muudatuse vastust saab sama võtme/päringuga korrata.

Autentimise, reeglistiku ja päringupiirangu vastused

Need vastused võivad tekkida igal registreeritud /v2/admin endpointil enne endpointipõhist töötlemist.

API juurdepääs sisaldub igas paketis. Tööruumi hosti adminApiEnabled seade keelamisel tagastatakse 404; lisafunktsiooni õiguse kaotamine eemaldab vaid mõjutatud pääsuulatused. Tekkiv ulatusest keeldumine kasutab allolevat vastust, mitte pääsutõendi uuendamise voogu.

Pääsuulatus, idempotentsus, parsimine, omand ja ootamatud tõrked

Ressursitee ID-d peavad olema positiivsed arvud. Mittepositiivne või mittearvuline :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId või :localUserId tagastab 422 ValidationError, mitte 400.

Asukoha ja võimsushalduse vead

Laadija vead

mapChargerErrors() kasutatakse laadija loomisel/uuendamisel, autentimisandmetel, pistikuseadetel, avalikul loetlemisel, QR-sisu lahendamisel, seadistuse muutmisel/uuesti laadimisel, püsivara käivitamisel, kõigi nelja põhikäsu ja koondajakava päringul.

Tavalised lugemistoimingud tagastavad ainult ühised 401/403/404/429/500/503 vastused ja 422 päringu/tee valideerimise. Laadija kustutamine võib tagastada ühise 500 PlainError, kui kustutamine nurjub ilma täpsema veavastuseta.

Aruandevead

Edukas eksport on kahendvormingus; kõik ekspordivead jäävad JSON-iks.

Tariifivead

Laadimisprofiilide vead

Kasutajadomeeni vead

Välja tuvastavad kasutaja valideerimisvead kasutavad ValidationError ja code; muud kasutajavead kasutavad CodedError. Kõik puuduva ressursi juhud kasutavad ühist olemasolu mitteavalduvat RESOURCE_NOT_FOUND vastust.

POST /users/invitations võib pärast sisu parsimist tagastada ka ühise 403 INSUFFICIENT_SCOPE, kui users:access puudub, või kui RFID anti ja users:rfid puudub. Kohalike kasutajate endpointid loetlevad iga nõutava pääsuulatuse Endpointide viites.

Kasutajate veakoodid kehtivad järgmiselt:

Kõik omandi ja puuduva ressursi tulemused neis rühmades, ka registreerimata e-post POST /users puhul, kasutavad ühist 404 RESOURCE_NOT_FOUND sisu.

Sisuta ja kordusvastused

Edukal 204 vastusel pole sisu. See kehtib iga dokumenteeritud kustutamise kohta, kus on 204 empty. Lõpetatud idempotentne kordus määrab Idempotency-Replayed: true ja kasutab salvestatud olekut/sisu; 204 puhul jääb HTTP vastus sisuta. API ei tagasta kunagi JSON-eduobjekti dokumenteeritud 204 toimingule.