Skip to main content

Dokumentatu API erroreak OpenAPI (aurretik Swagger bezala ezagutua) edo GraphQL-ren laguntzarekin

Azalpena​

REST APIek HTTP estatus kodigoak erabiliz bueltatzen dituzte emaitzak. APIaren erabiltzailearentzat guztiz beharrezkoa da APIaren egituraren eta baita ere errore posibleen berri izatea, erabiltzaileak errorea atzeman eta kontu handiz kudea dezake eta. Adibidez, zure APIaren dokumentazioak aurrez azaldu behar du 409 HTTP estatus kodea bueltatzen dela bezeroaren izena iada existitzen denean (APIak bezero berriak gordetzen dituela ziurtzat joz), APIaren erabiltzaileak egoera bakoitzerako bistaratze egokiena proposa dezan. OpenAPI (aitzina Swagger) APIaren dokumentaziorako eskema bat zehazten duen estandar bat da, dokumentazioa online modu errazean sortzea ahalbidetzen duten tresna ekosistema bat proposatuz. Begiratu hurrengo pantailako argazkiak beherago

Dagoeneko GraphQL erabiltzen baduzu zure APIaren helburuetarako, zure eskemak iada zorrozki bermatzen du zein errorek zein itxura eduki beharko luketen (dokumentuan laburbilduta) eta nola kudeatu beharko liratekeen zure bezero tresnekin. Gainera, komentarioz osatutako dokumentazioa ere gehi zenezake

GraphQL errore baten adibidea​

Adibide honek SWAPI erabiltzen du, Star Warsen APIa.

# huts egin beharko luke id ez baita zuzena
{
  filmea(id: "1ZmlsbXM6MQ==") {
    izenburua
  }
}
{
  "erroreak": [
    {
      "mezua": "Ez dago sarrerarik cache lokalean https://swapi.co/api/films/.../-rentzat",
      "lekuak": [
        {
          "ilara": 2,
          "zutabea": 3
        }
      ],
      "bidea": ["filmea"]
    }
  ],
  "datuak": {
    "filmea": null
  }
}

Blog aipua: "Zure deitzaileei zein errore gertatu diren esan behar diezu"​

Joyent blogeko “Node.js erregistratzea“ hitz gako bati esker sailkatua

Erroreak nola kudeatu behar diren aztertu dugu, baina funtzio berri bat idazten ari zarenean, nola bidaltzen dizkiozu erroreak zure funtzioa deitu duen kodeari? …Zein errore gerta litezkeen edo haiek zer esan nahi duten ez badakizu, esan nahi du zure programa ezin litekeela zuzena izan, txiripaz izan ezean. Beraz, funtzio berri bat idazten ari bazara, zure deitzaileei zein errore gerta litezkeen eta haiek zer esan nahi duten esan behar diezu…

Tresna erabilgarria: Swagger Online Dokumentazio Sortzailea​

Swagger API Eskema