Kuntratt tar-risponsi u l-iżbalji tal-API tal-amministrazzjoni

Dan il-fajl jikkompleta l-kuntratt tar-risponsi għal kull endpoint f'Referenza tal-endpoints. Aqra r-ringiela tal-endpoint għall-body tas-suċċess tiegħu u t-tabelli hawn taħt għal kull body mhux ta' suċċess kondiviża jew speċifika għall-endpoint. B'mod predefinit, l-iżbalji jużaw diversi strutturi ta' kompatibbiltà; min jagħmel is-sejħa jista' jagħżel envelope universali wieħed.

Envelope strutturat fakultattiv tal-iżbalji

Ibgħat dan il-header tat-talba lil kwalunkwe endpoint:

X-Error-Format: envelope

Il-paragun tal-valur ineħħi l-ispazji mit-truf u ma jagħmilx distinzjoni bejn ittri kbar u żgħar. B'dak il-valur eżatt, kull rispons JSON bi status ta' 400 jew aktar jiġi kkonvertit għal:

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

Eżempju ta' konverżjoni ta' body ta' validazzjoni predefinita:

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

Ir-regoli tal-konverżjoni huma eżatti:

• validationErrors isir details.fields, u code isir VALIDATION_FAILED anke meta l-body predefinita kellha wkoll kodiċi tad-dominju.
• Jinżamm code predefinit fl-ogħla livell meta ma jkunx hemm oqsma ta' validazzjoni.
• Proprjetajiet oħra fl-ogħla livell ħlief error, message, validationErrors u code jitmexxew f'details; pereżempju, limit tal-esportazzjoni tar-rapport isir details.limit.
• error tat-tip string fl-ogħla livell isir message. Jekk ma jeżistix, jintuża l-istatus ta' riżerva.
• Il-kodiċijiet ta' riżerva huma AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 u 4xx oħra mhux klassifikati), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) u INTERNAL_ERROR (5xx oħra, inkluż 503).
• requestId huwa l-header eżatt tar-rispons X-Request-Id. ID tat-talba pprovdut minn min jagħmel is-sejħa jintuża biss meta jaqbel ma' [A-Za-z0-9._:-]{1,128} wara li jitneħħew l-ispazji mit-truf; inkella s-server jiġġenera UUID.

Din it-trasformazzjoni ma tbiddilx l-istatus jew il-headers mhux tal-body. Tapplika wkoll għal ripetizzjonijiet idempotenti skont il-header X-Error-Format tat-talba ripetuta. Risponsi ta' suċċess binarji jibqgħu binarji; l-iżbalji JSON tagħhom jitqiegħdu f'envelope. It-tabelli li jifdal juru l-bodies predefiniti; l-applikazzjoni tar-regoli ta' hawn fuq tagħti l-body l-oħra possibbli tar-rispons għal kull ringiela.

Notazzjoni tar-risponsi

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

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

PlainError = { error: string }

error u t-test tal-messaġġi tal-validazzjoni huma deskrittivi, mhux identifikatur stabbli għall-programmi. Iddistingwi l-każijiet skont code meta preżenti. Il-validazzjoni tat-talba tirritorna 422 ValidationError; il-validazzjoni ta' oġġett sħiħ tista' tipproduċi { "validationErrors": {} } meta ma jiġi identifikat ebda qasam individwali. JSON invalidu u żbalji mhux mistennija jirritornaw il-500 PlainError globali muri hawn taħt.

L-eżempji JSON kollha juru l-istruttura eżatta tal-body. It-test muri bħala <message> huwa l-messaġġ ta' validazzjoni jew operazzjoni rritornat u huwa string JSON, mhux valur litterali bejn parentesi angolari.

Ordni tal-ipproċessar tat-talbiet

It-talbiet jiġu pproċessati f'din l-ordni:

1. konfigurazzjoni u awtentikazzjoni tat-tokens tal-ispazju tax-xogħol;
2. politika tal-host u limiti tar-rata tat-token/ispazju tax-xogħol;
3. filtrazzjoni tad-drittijiet attwali;
4. għal kull mutazzjoni, validazzjoni/claim tal-idempotenza;
5. kontrolli tal-ambiti tal-endpoint, validazzjoni tat-talba u l-operazzjoni mitluba.

Għaldaqstant, mutazzjoni b'token validu iżda b'ambiti insuffiċjenti xorta trid tibgħat Idempotency-Key. Rispons komplut ta' mutazzjoni 403, 404, 409 jew 422 jista' jiġi ripetut għall-istess ċavetta/talba.

Risponsi tal-awtentikazzjoni, il-politika u l-limitu tar-rata

Dawn ir-risponsi jistgħu jseħħu fuq kull endpoint reġistrat /v2/admin qabel l-ipproċessar speċifiku għall-endpoint.

L-aċċess API huwa inkluż f'kull pjan. Id-diżattivazzjoni tas-setting adminApiEnabled tal-host tal-ispazju tax-xogħol tirritorna 404; it-telf ta' dritt għal funzjoni addizzjonali jneħħi biss l-ambiti affettwati. Iċ-ċaħda tal-ambitu li tirriżulta tuża r-rispons hawn taħt, mhux fluss ta' tiġdid tat-token.

Żbalji tal-ambiti, l-idempotenza, il-parsing, is-sjieda u mhux mistennija

L-IDs tal-path tar-riżorsi jridu jkunu numri pożittivi. :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId jew :localUserId mhux pożittiv jew mhux numeriku jirritorna 422 ValidationError, mhux 400.

Żbalji tas-siti u tal-ġestjoni tal-qawwa

Żbalji taċ-ċarġers

mapChargerErrors() jintuża għall-ħolqien/aġġornament taċ-ċarġers, kredenzjali, settings tal-konnetturi, elenkar pubbliku, riżoluzzjoni tal-payload QR, mutazzjoni/aġġornament tal-konfigurazzjoni, bidu tal-firmware, l-erba' kmandi bażiċi kollha u t-talba tal-iskeda komposta.

Operazzjonijiet sempliċi tal-qari jirritornaw biss ir-risponsi kondiviżi 401/403/404/429/500/503 flimkien mal-validazzjoni query/path 422. It-tħassir ta' ċarġer jista' jirritorna l-500 PlainError kondiviż jekk ifalli mingħajr rispons ta' żball aktar speċifiku.

Żbalji tar-rapporti

L-esportazzjoni li tirnexxi hija binarja; l-iżbalji kollha tal-esportazzjoni jibqgħu JSON.

Żbalji tat-tariffi

Żbalji tal-profili tal-iċċarġjar

Żbalji tad-dominju tal-utent

Żbalji ta' validazzjoni tal-utent li jidentifikaw qasam jużaw ValidationError flimkien ma' code; żbalji oħra tal-utent jużaw CodedError. Il-każijiet kollha ta' riżorsi nieqsa jużaw ir-rispons kondiviż RESOURCE_NOT_FOUND li ma jiżvelax ir-riżorsi.

POST /users/invitations jista' wkoll jirritorna l-403 INSUFFICIENT_SCOPE kondiviż wara l-parsing tal-body jekk users:access ikun nieqes, jew jekk ġie pprovdut RFID u users:rfid ikun nieqes. L-endpoints tal-utenti lokali jelenkaw kull ambitu meħtieġ f'Referenza tal-endpoints.

Il-kodiċijiet tal-iżbalji tal-utent japplikaw kif ġej:

L-eżiti kollha tas-sjieda u tar-riżorsi nieqsa f'dawk il-familji, inkluża email mhux reġistrata fuq POST /users, jużaw il-body kondiviża 404 RESOURCE_NOT_FOUND.

Risponsi mingħajr body u ta' ripetizzjoni

Rispons ta' suċċess 204 ma jkollux body. Dan japplika għal kull tħassir dokumentat li jelenka 204 empty. Ripetizzjoni idempotenti kompluta tissettja Idempotency-Replayed: true u tuża l-istatus/body maħżuna; għal 204, ir-rispons HTTP jibqa' mingħajr body. L-API qatt ma jirritorna oġġett JSON ta' suċċess għal operazzjoni dokumentata 204.