2 - API:n / Rajapinnan julkaisu

Last modified by Xwiki VePa on 2024/02/07 07:37

Tässä ohjeessa kerrotaan ohjeet rajapinnan julkaisemiseen HY:n Api gateway alustassa.

1 API-Gateway alusta

Mikäli haluat tietää yleiskuvauksen valitusta API-gateway alustasta, niin käy lukemassa ensimmäinen ohjesivu: 1 - API-Gateway (Gravitee) yleiskuvaus.

2 API-hallinta

Helsingin yliopisto on laatinut API-hallintamallin, jossa linjataan, mitä API:n julkaisussa on syytä huomioida ja millä tavoin API-hallintaa toteutetaan. Mikäli et ole vielä tutustunut API-hallintamalliin, on voi siihen tutustua siihen ennen API:n julkaisua. 

API-hallintamalli

3 Checklist / tarkistuslista ennen rajapinnan julkaisua

Ennen julkaisua on syytä tarkistaa seuraavat kohdat ennen julkaisun tekemistä.

1 Ohjeiden lukeminen ja pääsy API-gateway alustaan

Mikä

Tarkennus

Tarkistettu  (pvm)

Huomioita

1a

API-gateway alustan yleiskuvauksen lukeminen (suositus)




1b

API-rajapinnan julkaisuohjeen lukeminen (suositus)




1c

Tämä checklist täytettynä




1d

Käyttöoikeuden hakeminen




2 Vaatimukset rajapintaan liittyen

2a

Rajapinnalla on omistaja

Yksittäisten API:n julkaisuun liittyvät toimet kuuluvat API:n omistajalle/kehittäjälle. API:n omistaja määrittelee myös sen, kuka rajapintaa saa käyttää ja millaisilla ehdoilla. Rajapintojen julkaisu ja tuen antaminen yksittäisen rajapinnan osalta kuuluu API:n omistajalle/kehittäjälle.



2b

Rajapinnan dokumentaatio (swagger) on tuotettu vaaditulla tarkkuustasolla.

Rajapinnan kuvaukselta edellytetään OpenAPI (Swagger) -standardin mukainen kuvaus, joka sisältää:

  • palvelun nimi ja kuvaus (mitä palvelu tekee)
  • palvelun teknisen ylläpidon yhteysosoite
  • julkaistava palvelun osoite gatewayllä. Ensimmäisessä swagger-importissa vaaditaan yksilöivä basePath tai server urlin path, johon api oletuksena julkaistaan. Esimerkiksi basepath: /organisation tai url: https://api.helsinki.fi/organisation
  • JOS julkaistava palvelu sisältää henkilötietoa, julkaisu tulee tehdä basePath /securen alle esimerkiksi /secure/persondata
  • rajapinnan kutsuosoitteet kuten /organisation/financial sekä niiden tarkat kuvaukset
  • kutsuesimerkit tarkalla tasolla: Onko GET/POST/muu, json vai muu, mahdolliset annettavat lisäparametrit, pakolliset kentät
  • sanomamuodot: application/json, text/xml, palautettavan tai lähetettävän objektin tarkka kuvaus kenttien tyyppeineen sekä rajoitteineen(maksimi pituus)
  • tunnistautuminen: vaaditaanko esimerkiksi api-avain joillekin metodeille/koko APIlle. Oletuksena vaaditaan vähintään Api-avain jokaiselle rajapinnalle. On tärkeää muistaa nämä määritykset swagger-dokumentaatiossa.
  • virheilmoituksien kuvaukset: esimerkiksi 404 = ei löydy
  • lisenssiehdot, jos on




4 Rajapinnan avaaminen API-gateway-alustalle

Taustapalvelu, joka julkaisee rajapinnan tulee avata tietoliikenteellisesti API-gateway alustalle. Api-gateway nodet sijaitsevat seuraavissa osoitteissa

Node

Tuotantoympäristön node

IP-osoite

1

api-prod-gw-1-19.it.helsinki.fi

128.214.224.137

2

api-prod-gw-2-19.it.helsinki.fi 

128.214.224.226




Node

Testiympäristön node

IP-osoite

1

api-test-1-19.it.helsinki.fi

128.214.224.232


5 Rajapinnan nimeäminen

Rajapinnan nimeämiseen on syytä kiinnittää huomiota, koska huonosti nimetty rajapinta aiheuttaa helposti sekaannusta kutsujissa


  • Rajapinnan nimen ensimmäinen osa voi olla lähettävän järjestelmän nimi tai muu lähettäjää kuvaava substantiivi ja seuraava osa kuvaa lähetettävää tietoa.
    • esim. /message-center/notification(s) 
  • Kuvattu tieto on yksikössä, jos rajapinta palauttaa yhden tiedon ja monikossa jos palautettavia tietueita on useampia
  • Rajapinnan nimen tulee olla kuvaava ja selkeä, niin että kutsuva taho ymmärtää mitä rajapintaa on kutsumassa. Rajapinnan nimi on miellään oikea sana
  • Rajapinta tulee mielellään olla englanniksi tai samalla kielellä, kun palautettava tieto on (jos rajapinta palauttaa tiedon vain suomeksi voi rajapinnan nimikin olla suomeksi)
  • Käytä "/"-merkkiä erottaaksesi rakenteisen datan alaosat toisistaan
    • esim: /message-center/notifications/{id}/recipient
  • Käytä "-"-merkkiä helpottaaksesi pitkien nimien luettavuutta
    • esim: message-center-test
  • /secure/ polku on turvattu alue ja siellä julkaistut apit vaativat tls client sertifikaatin
    • esim. /secure/message-center/notifications


6 Polun määrittely


API:n polku määritellään API-gatewaylle ja se reititään kohde palvelimella oikeaan polkuun. Konfigurointeja tehdään seuraaviin kohtiin:


Swagger-dokumentti

Configuration -välilehti

Endpoints konfiguration

  • Mihin liikenne ohjataan

Entrypoint

  • Esim. message-center (mikä osoite näytetään ulospäin)





Parasta ennen: 09.06.2020

Vaikeustaso

Tekninen:

Hallinnollinen:  

Koordinointi:  

Kalenteriaika:  


Vastuunjako

Ohjeistus

Tekninen alusta

tike-integraatiopalvelu@helsinki.fi


Yhteystietoja

tike-ohjelmistotuotanto@helsinki.fi