Did they get it right at Finavia API with 3 Scale?

5. toukokuuta 2019

Yksi suomen API-skenen suurista lanseerauksista tänä syksynä on ollut Finavian hallinnoima Finavia API. Se tarjoaa julkista rajapintaa lähtöjen, saapumisten ja jonokokojen pyytämiseen Suomen lentokentiltä.

API-harrastajaja tämä oli jotain, joka minun piti vain saada käsiini ja jaan mielelläni löydökseni kaikkien eduksi.

Teemme paljon API-konsultointia ja koulutusta Osaangolla, mutta yksi tärkeimmistä palveluistamme on API Design -arvioinnit, jotka testaavat APIa sekä teknisen toteutuksen, käytettävyyden että markkinoitavuuden osalta kehittäjien näkökulmasta. Kehitämme ja tuemme myös avointa Creative Commons -menetelmää  hyvien liiketoimintasuuntautuvien APIen luomiseksi kevyellä tavalla.

https://www.apiopscycles.com/

Finavian API- ja kehittäjä-portaali - melkein siellä, mutta parantamisen varaa

Yleisesti ottaen onnistuin käyttämään APIa. Se on melko yksinkertaista. Siinä on joitakin

Mutta prosessissa oli joitain ongelmia, ennen kuin onnistuin edes tekemään ensimmäisen API-pyyntöni.

Käyn läpi löydöksiä. Tämä ei tietenkään ole normaali täydellinen arviointipalvelumme ja vaikka APIssasi olisi kaikki nämä ongelmat korjattu, yleensä löytyy paljon muita. Mutta näiden korjaaminen on jo hyvä alku.

Osa ongelmista on vakioita 3 Scale API-hallinta alustalle, Finavia käyttää vakioasetuksia. 3 Scalen osti jokin aika sitten Red Hat, jonka IBM osti hiljattain.

Sisäänkirjautuminen ja navigointi

Kirjaudu sisään Finavia kehittäjäportaaliin

Käyttäjätilin luominen alustalle oli melko helppoa. Yllä oleva kuva on ensimmäinen näyttö, jonka sain kirjautumisen jälkeen.

"Your Applications" -tekstin tyyli on trendikäs, mutta ehkä äänensävyä ja sisältöä olisi voitu mukauttaa enemmän lentomaailmaan sopivaksi. Minulla oli myös halu napsauttaa kuvakkeita, erityisesti "Add application" päästäkseni todella siihen näkymään, mihin voin lisätä sen. Mutta ei, ne eivät olleet painikkeita tai linkkejä.

Minne sitten menen luomaan sovelluksen?

Tietenkin minun on napsautettava vaaleansinistä "Details" alakulmassa. Kuinka intuitiivista. Erityisesti silloin, kun valittavana on 2 ohjelmointirajapintaa, julkiset lennot (v0, mikä !?!) ja jonot. Molemmissa on "Tiedot" -painike.

Joten mennään yksityiskohtiin.... Seikkailu alkaa!

Sovelluksen luominen - tai sen yrittäminen....

Monet API-hallinta alustat edellyttävät, että käyttäjä luo sovelluksen eli antaa vähän tietoa tietystä käyttötapauksesta tai asiakassovelluksesta ja saa vastineeksi sovelluskohtaisen sovellustunnuksen tai asiakastunnuksen, jota käytetään API-pyyntöjen todentamiseen. Joskus yhdessä API-avaimen kanssa, joskus joidenkin muiden todennusmenetelmien kanssa.

Sovellusta yritettiin luoda ilman kuvausta, koska kenttää ei ollut merkitty pakolliseksi kentäksi.

Näyttöön ilmestyi virhesanoma, jonka jälkeen SERVICE-tietojen tilalle muuttui ",",

Tämä aiheutti uuden sovelluksen luomisen epäonnistumisen.

Sovelluksen luominen epäonnistuu

Ja sitten nähdään tavallinen 3Scale-virhesivu. Tämä on hieman hämmentävää, koska normaalina API-kehittäjänä minulla ei ehkä ole aavistustakaan siitä, mikä on 3Scale ja mitä tekemistä sillä on Finavian APIn kanssa. Edelliselle sivulle ei myöskään ole tietä takaisin.

Yhtäkkiä saan tavallisen virheilmoituksen ilman Finavia-brändäystä

Lopussa onnistuin luomaan sovelluksen onnistuneesti ja saamaan API-avaimeni. Se oli hieman hämmentävää, olin sovellussivulla ja yhtäkkiä API-dokumentaatio oli Documentation-nimisessä alivälilehdessä. Mutta löysin sen.

Hämmentävä navigointi, mutta sain sovelluksen luotua

Eteenpäin, rakkaat API-kehittäjät, maaliviiva häämöttää!

Hanki minulle joitain lentoja... lentoja... Kaikki... Kaikki... Kaikuuko siellä?

Nyt kun minulla oli API-avaimeni, pystyin keskittymään itse Flight APIin.

Noin 5 sekunnin kuluttua dokumentaation läpi käymisen jälkeen minulla oli kysymyksiä päätepisteen suunnittelusta.

Miksi käyttää lyhyitä versioita (dep ja arr) lentotyypeille, ja miksi sitä ylipäätään kutsutaan nimellä "type"?

Miks ei yksinkertaisesti ole erilaisia päätepisteitä saapuville ja lähteville. Ensimmäinen ajatus mikä minulle tuli nähdessäni "flight_type" on valita kotimaisista tai kansainvälisistä, ei saapumisista ja lähdöistä. Ja miksi säästää tilaa täällä?

Katsotaanpa myös, mikä perus-URL-osoite ja enpoint-URL-osoite ovat yhdistettynä parametreihin.

https://api.finavia.fi/flights/public/v0/flights/all/all

Ei voi olla tuntematta, että joku on keksinyt REST-kaiun täällä... Tiedäthän "/lennot... /lennot... /all... /all...

On mielenkiintoinen, mutta ei välttämättä väärä päätös laittaa kaikki suodattimet (lentokenttä, lähdöt tai saapumiset) URI-parametreihin, koska tässä tapauksessa voit jopa väittää, että ne tunnistavat erilaisia resursseja. Tämä on kuitenkin tie, jota ei pidä jatkaa.

Lopullinen ajatus endpointin suunnittelusta on, että dokumentaation perusteella minulla ei ole aavistustakaan, mitä tulokset tulevat minulle antamaan.

Ensimmäisen onnistuneen pyynnön jälkeen epäilen, että saan saapumisia 24 tuntia aiemmin, enkä oikeastaan tiedä kuinka monta tuntia tulevaisuuteen. Ehkä suodattimia täällä? tai ainakin asiakirjoja? Myös lennon numerolla tai määränpäällä etsiminen voi olla mukavaa, sitä teen yleensä Finavian palvelun käyttöliittymäversiolla.

Datan tuoreus ja kyselyhulluus

Jos tietoja päivitetään vain 1 minuutissa ja kyselyväli on vähintään 30 s, miksi hookeja ei ole? Tarkoitan, että webhookeja tai REST-hookeja ei ole saatavilla?

Unauthorized vai Forbidden - siinäpä vasta kysymys

Unauthorized 401 ja Forbidden 403 eivät ole sama asia!

Jopa sen jälkeen, kun sain API-avaimet, dokumentaatiossa näkyi vielä punainen kuvake, jossa sanottiin että tarvitsen API-avaimia.

Jos uskaltauduin sivun alareunaan, löysin Try me -painikkeen, jonka avulla voin todella suorittaa pyynnön antamatta avaimia erikseen.

Ilman API-avaimia Try me -pyyntö johtaa 403 Forbidden- ja virhesanomaan "Authentication parameters missing". Oikea HTTP-tilakoodi tässä tapauksessa on 401.

Unauthorized. 403 Kielletty tulisi varata tunnistetuille pyynnöille, joihin käyttäjällä ei vain ole valtuutusta.

Tässä nimenomaisessa APIssa, joka sisältää vain julkisia tietoja on ihan ok olla käytössä vain API-avain header-tiedoissa. Se on paljon parempi kuin ei mitään tai pistää ne kyselyparametreihin. Älä vain käytä sitä arkaluontoisempiin tietoihin, ja edes julkisissa rajapinnoissa se ei välttämättä ole paras ratkaisu.

Status-koodien tila

Ainoa dokumentoitu tilakoodi onnistuneelle vastaukselle on 200. Kun testasin APIa, yritin löytää lentoja ilman olemassaolevaa lentokenttää, XXX. Sain empty Flights -noden. Tässä tapauksessa odotin tyhjää tulosta ja 204 -tilakoodia.



xmlns="http://www.finavia.fi/FlightsService.xsd"/>

Koska kaikki parametrit ovat URI-parametreja, tässä tapauksessa ainoat vaihtoehdot muille HTTP-tilakoodeille kuin 200 ovat 404, 401 (ei 403) luvattomalle) ja saisin todennäköisesti 500, jos palvelin epäonnistuisi.

Yleisesti ottaen palvelimelta tulevat vastausotsikot ovat melko mukavia ja siistejä. Ehkä hieman liikaa tietoja vastausotsikoissa palvelimesta ja todennusratkaisusta makuuni, joka liittyy tietoturvakysymyksiin.

Tietoa tietotyypeistä

Minulla on vain yksi kysymys: miksi XML, ja miksi se on ainoana vaihtoehtona?

Pluspisteet ISO-päivämäärien käyttämisestä UTC: ssä aikavyöhykkeiden kanssa!

Mutta valtava miinus siitä, ettei tarjottu asiakirjoja vastausten ominaisuuksista?

Sisäisten tietorakenteen nimien julkaisemista suoraan ei yleensä suositella. Kysyn vain, mikä on mfltnr vai ablk-d?

Englantia muillekin kuin lentäjille, kiitos?

TMP
SK4243
2018-11-06T10:25:00Z
20181106
GFBXD
AT76

Tämä oli vain esimerkki yhdestä APIsta. Toivottavasti tämä auttaa sinua. Miksi näin pienet asiat ovat niin merkittäviä?

Jotkin asiat ovat  halpoja tehdä suunniteluvaiheessa ja kalliita korjata julkaisun jälkeen, ja niistä muodostuu lisäkuluja käyttäjätukityöntekijöiden, alhaisempien käyttäjämäärien ja suurempien siirtymäkustannuksien  kautta uusiin versioihin

P.s. Julkaistuani tämän blogikirjoituksen Finavian Tommi Vihervaara kommentoi, että he ovat jo alkaneet kehittää Flights API v2.0:sta, joka on määrä julkaista vuonna 2019. Tommin mukaan monet blogissa mainituista asioista korjataan uudessa versiossa ja jopa jotkut, joita ei mainita täällä. Jotkut korjaukset liittyvät 3Scale-alustaan, joka toivottavasti korjataan seuraavissa versioissa.

Jos tarvitset arvion omasta APIstasi, käymme läpi jopa 20 asiaa listastamme tarkistaaksemme APIsi ja dokumentaatiosi.

Takaisin blogiin

viimeisimmät blogimme

Uutisia, asiakastarinoita, parhaita käytäntöjä ja paljon muuta - katso, mitä me ja asiakkaamme ja kumppanimme olemme tehneet viime aikoina

Miksi APIt kannattaa tuotteistaa?
Mitä hyötyä APIen tuotteistamisesta on? Lue lisää täältä!
16. kesäkuuta 2021
Millainen on hyvä API-tuotepäällikkö?
Kaksi API-gurua, Marjukka Niinioja ja Claire Barrett keskustelevat API-tuotepäällikön roolista ja odotuksista ja jakavat itetämystään menestyksekkäästä API-tuotehallinnasta.
14. kesäkuuta 2021
Osaango & KAVI – innovatiivisia, älykkäitä hankintoja
Kansallinen audiovisuaalinen instituutti KAVI tallentaa vuosittain valtavat määrät dataa, ja vastaa muun muassa kotimaisten elokuvien sekä televisio- ja radio-ohjelmien säilyttämisestä. Kriittisen tärkeässä osassa KAVIn toiminnassa on tekoäly. Osaangon Marjukka Niinioja ja Tessa Viitanen sparrasivat KAVIa heidän mittavassa toiminnan ja tekniikan muutos-casessa tekoälyyn pohjautuvien ratkaisujen, innovatiivisten hankintamenettelyjen, ohjelmistokehitysprosesssien ja arkkitehtuurin osalta.
27. toukokuuta 2021