Siirry pääsisältöön

Day 1.75 of Solidabis Code Challenge 2022 – En ymmärrä mitään

Julkaistu Aiheet: Suomeksi, Nettisovellukset, Koodihaaste.

Olen nettisovellusaloittelija, joka tekee Solidabiksen koodihaastetta 2022. Päivitän, kuinka minulla menee ja jaan tuskani julkisesti, kun yritän rakentaa äänestyssovellusta ravintolan päättämiseksi!

Tällä kertaa ihmettelen, että mikä on API ja miten Swagger liittyy siihen.

APInointia

API (application programming interface) on käsittääkseni kyseessä, kun kaksi eri ohjelmaa pyrkivät keskustelemaan keskenään. Jos ohjelmalla on API, niin se luo ‘putken’, jota kautta tieto siirtyy ohjelmasta toiseen eli niiden välille muodostuu rajapinta.

Koodihaasteen tapauksessa API muodostuu backend-ohjelman ja lounaat.info -palvelun välille. API ikään kuin kertoo backend-ohjelmalle, miten tietoja noudetaan ja sitä kautta APIn dokumentaatio kertoo minulle miten sitä käytetään.

Näin saan esimerkiksi kaikkien Helsingin ravintoloiden listan backendin kautta, koska se osaa kommunikoida lounaat.info -palvelun kanssa ja järjestellä tiedon muotoon, jota minun on helppo käsitellä.

Mikä ihmeen “Swagger”?

Swagger on työkalu, joka käyttää avoimen lähdekoodin periaatteita APIen dokumentaation esittelyyn ja käyttöönottoon. Swagger käyttää OpenAPI määrityksiä, jotka mahdollistavat ns. yhteisen kielen kaikille APIlle, joita palvelussa on. On siis helpompi oppia se kuin tuhansia muita.

Se ei kuitenkaan auttanut minua selvittämään, miten Swaggerin openAPI dokumentaatiota luetaan. Swaggerissa oli enemmän ohjeita sille, miten teet sinne oman APIsi kuin, että miten muut voivat sitä käyttää. Nämä perustuvat HTTP-metodeihin.

Ilmeisesti on neljä olennaista HTTP-metodia, kun APIa käytetään:

  1. GET tarkoittaa, että tämän ‘putken’ kautta saa haettua tietoa APIn läpi. Esimerkiksi listan ravintoloista.
  2. POST tarkoittaa, että voin viedä tietoa APIn kautta. Esimerkiksi äänet, jotka kukin ravintola saa.
  3. PUT tarkoittaa, että voin luoda jonkin uuden objektin tai päivittää jotain olemassa olevaa (en oikein tajua vielä).
  4. DELETE on aika itsestäänselvä. Voin poistaa jotain tietoa tätä kautta. Esimerkiksi, jos jokin ravintola on syytä poistaa kokonaan tietokannasta, niin voisin tehdä sen tällä.

Kaikkia näitä ei kuitenkaan ole Swaggerin openAI -sivulla, joka koskee tätä kyseistä tehtävää. PUT ja DELETE puuttuvat kokonaan. Ehkä minun ei siis haluta poistavan tai lisäävän mitään olennaisia tietoja – pelkästään muokkaavan tai hakevan niitä.

Ai, niin! Minun piti käyttää jotain “gradlea”, että sain edes openAI-sivun avattua. En tiedä vielä mikä se on.

Käykö mikään tästä järkeen? Ei ainakaan kaikki minulle. Selitä minulle ja muille, jos tiedät paremmin!