Admin API:n vastaus- ja virhesopimus

Tämä tiedosto täydentää jokaisen Endpoint-viitteen endpointin vastaussopimuksen. Lue onnistumisrunko endpointin riviltä ja kaikki yhteiset tai endpoint-kohtaiset epäonnistumisrungot alla olevista taulukoista. Oletusarvoisesti virheillä on useita yhteensopivuusrakenteita; kutsuja voi valita yhden yleiskääreen.

Valinnainen rakenteinen virhekääre

Lähetä tämä pyyntöotsake mille tahansa endpointille:

X-Error-Format: envelope

Arvovertailussa poistetaan reunavälit eikä kirjainkoolla ole merkitystä. Tällä täsmällisellä arvolla jokainen JSON-vastaus, jonka tila on 400 tai suurempi, muunnetaan muotoon:

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

Oletusvalidointirungon muunnosesimerkki:

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

Muunnossäännöt ovat täsmälliset:

• validationErrors muuttuu arvoksi details.fields ja code arvoksi VALIDATION_FAILED, vaikka oletusrungolla olisi myös toimialuekoodi.
• Oletusarvoinen ylimmän tason code säilytetään, kun validointikenttiä ei ole.
• Muut ylimmän tason ominaisuudet paitsi error, message, validationErrors ja code siirtyvät kohtaan details; esimerkiksi raporttiviennin limit muuttuu arvoksi details.limit.
• Ylimmän tason merkkijono error muuttuu arvoksi message. Jos sitä ei ole, käytetään tilan vara-arvoa.
• Varakoodit ovat AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 ja muut luokittelemattomat 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) sekä INTERNAL_ERROR (muut 5xx, myös 503).
• requestId on täsmällinen X-Request-Id-vastausotsake. Kutsujan antamaa pyyntötunnistetta käytetään vain, jos se vastaa [A-Za-z0-9._:-]{1,128} reunavälien poiston jälkeen; muutoin palvelin luo UUID:n.

Muunnos ei muuta tilaa eikä runkoon liittymättömiä otsakkeita. Se koskee myös idempotentteja toistoja toistopyynnön X-Error-Format-otsakkeen mukaan. Binääriset onnistumisvastaukset pysyvät binäärisinä; niiden JSON-virheet kääritään. Muut taulukot näyttävät oletusrungot; yllä olevilla säännöillä saadaan jokaisen rivin toinen mahdollinen vastausrunko.

Vastausmerkinnät

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 validointiviestin teksti ovat kuvailevia, eivät vakaita ohjelmallisia erottimia. Haarauta arvon code mukaan, kun se on mukana. Pyyntövalidointi palauttaa 422 ValidationError; koko objektin validointi voi tuottaa { "validationErrors": {} }, kun yksittäistä kenttää ei tunnisteta. Virheellinen JSON ja odottamattomat virheet palauttavat alla esitetyn globaalin 500 PlainError-vastauksen.

Kaikki JSON-esimerkit esittävät rungon tarkan rakenteen. <message>-tekstinä esitetty arvo on palautettu validointi- tai toimintoviesti ja JSON-merkkijono, ei kirjaimellinen kulmasulkeissa oleva arvo.

Pyyntöjen käsittelyjärjestys

Pyynnöt käsitellään tässä järjestyksessä:

1. työtilatunnuksen määritys ja todennus;
2. isännän käytäntö ja tunnuksen/työtilan pyyntörajoitukset;
3. nykyisten käyttöoikeuksien suodatus;
4. jokaiselle muutokselle idempotenssin validointi/varaus;
5. endpointin käyttöaluetarkistukset, pyynnön validointi ja pyydetty toiminto.

Siksi myös muutos, jonka tunnus on kelvollinen mutta käyttöalueiltaan riittämätön, edellyttää Idempotency-Key. Valmis 403-, 404-, 409- tai 422-muutosvastaus voidaan toistaa samalla avaimella ja pyynnöllä.

Todennus-, käytäntö- ja pyyntörajoitusvastaukset

Nämä vastaukset voivat esiintyä jokaisessa rekisteröidyssä /v2/admin-endpointissa ennen endpoint-kohtaista käsittelyä.

API-käyttö sisältyy jokaiseen tilaukseen. Työtilan isännän adminApiEnabled-asetuksen poistaminen käytöstä palauttaa 404; lisätoiminnon käyttöoikeuden menettäminen poistaa vain kyseiset käyttöalueet. Seurauksena oleva käyttöalueen esto käyttää alla olevaa vastausta, ei tunnuksen uusimismenettelyä.

Käyttöalue, idempotenssi, jäsentäminen, omistus ja odottamattomat virheet

Resurssipolkujen tunnisteiden on oltava positiivisia lukuja. Ei-positiivinen tai ei-numeerinen :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId tai :localUserId palauttaa 422 ValidationError, ei 400.

Kohteiden ja tehonhallinnan virheet

Laturien virheet

mapChargerErrors() käytetään laturin luonnissa/päivityksessä, tunnistetiedoissa, liitinasetuksissa, julkisessa listauksessa, QR-sisällön ratkaisussa, määrityksen muutoksessa/uudelleenlatauksessa, laiteohjelmiston käynnistyksessä, kaikissa neljässä peruskomennossa ja yhdistelmäaikataulupyynnössä.

Tavalliset lukutoiminnot palauttavat vain yhteiset 401/403/404/429/500/503-vastaukset ja 422-kysely-/polkuvalidoinnin. Laturin poisto voi palauttaa yhteisen 500 PlainError-vastauksen, jos poisto epäonnistuu ilman tarkempaa virhevastausta.

Raporttivirheet

Onnistunut vienti on binäärinen; kaikki vientivirheet pysyvät JSONina.

Tariffivirheet

Latausprofiilien virheet

Käyttäjätoimialueen virheet

Kentän yksilöivät käyttäjävalidointivirheet käyttävät ValidationError ja code; muut käyttäjävirheet käyttävät CodedError. Kaikki puuttuvan resurssin tapaukset käyttävät yhteistä RESOURCE_NOT_FOUND-vastausta, joka ei paljasta resurssin olemassaoloa.

POST /users/invitations voi myös palauttaa yhteisen 403 INSUFFICIENT_SCOPE-vastauksen rungon jäsentämisen jälkeen, jos users:access puuttuu tai jos RFID annettiin ja users:rfid puuttuu. Paikalliskäyttäjäendpointit luettelevat kaikki vaaditut käyttöalueet Endpoint-viitteessä.

Käyttäjävirhekoodit ovat käytössä seuraavasti:

Kaikki omistus- ja puuttuvan resurssin tulokset näissä ryhmissä, mukaan lukien rekisteröimätön sähköposti toiminnossa POST /users, käyttävät yhteistä 404 RESOURCE_NOT_FOUND-runkoa.

Rungottomat ja toistetut vastaukset

Onnistuneessa 204-vastauksessa ei ole runkoa. Tämä koskee jokaista dokumentoitua poistoa, jossa mainitaan 204 empty. Valmis idempotentti toisto asettaa Idempotency-Replayed: true ja käyttää tallennettua tilaa/runkoa; tapauksessa 204 HTTP-vastaus pysyy rungottomana. API ei koskaan palauta JSON-onnistumisobjektia dokumentoidulle 204-toiminnolle.