Tässä dokumentissa kuvataan Velhon rajapintojen versio 2. Rajapintaversio 1 on vanhentunut eikä sen päälle tule enää tehdä uusia toteutuksia.

Versiossa 2 toteutetut muutokset versioon 1 nähden:

  • Autentikaatio tapahtuu OAuth2 client credentials -mekanismilla
  • Kaikkien rajapintaa käyttävien käyttäjätunnukset ja salasanat ovat muuttuneet
  • Rajapinnan palveluiden polut ovat muuttuneet
  • Palvelukohtainen dokumentaatio on nyt saatavissa suoraan rajapintojen kautta (poislukien latauspalvelu)
  • Latauspalvelu toimii nyt osana samaa rajapintaa eikä enää erikseen
    • Tulevaisuudessa latauspalvelun tiedostoissa oleva metatieto-objekti tulee luultavasti poistumaan, ja tähän tulee varautua

Rajapintojen käyttöohje

Velho tarjoaa pääsyn tietosisältöönsä REST-tyyppisten HTTP-rajapintojen kautta. Rajapintojen käyttäminen vaatii, että käyttävälle taholle on luotu käyttäjätunnukset rajapintaan. Käyttäjätunnuksiin sidotut käyttöoikeudet rajaavat tarkemmalla tasolla, mihin rajapintoihin on pääsy.

Rajapinnoista on tarjolla sekä ns. staging-ympäristö (stg) että varsinainen tuotantoympäristö (prd). Staging-ympäristöä voi käyttää järjestelmätestaukseen, ja se on rajapintojen osalta identtinen tuotantoympäristön kanssa.

Käyttäjätunnukset ovat ympäristökohtaisia.

Tämän ohjeen esimerkit käyttävät staging-ympäristöä. Tuotantoympäristön osoitteet rakentuvat samalla periaatteella.

Autentikaatio

Kaikki rajapintoihin tehtävät kutsut tulee autentikoida. Tämä tapahtuu liittämällä kutsuun OAuth v2 -standardin mukainen autorisaatioheader. Sen muodostamiseen tarvittava autorisaatio-token puolestaan saadaan suorittamalla API-käyttäjätunnuksien avulla autentikaatio erilliseen rajapintaan, joka palauttaa onnistuneen autentikaation jälkeen rajoitetun ajan (tällä hetkellä 1 tunti) voimassa olevan autorisaatio-tokenin.

Autentikaatiopyynnön tekeminen

Autentikaatiopyyntö tehdään OAuth2-standardin (RFC 6749) mukaisen client credentials grant flow:n kautta. Velhon OAuth2 token-endpointit ovat

  • Staging-ympäristö: https://auth.stg.velho.vayla.fi/oauth2/token
  • Tuotantoympäristö: https://auth.prd.velho.vayla.fi/oauth2/token

Pyyntö tulee tehdä

  • HTTP Basic Authentication -autentikoituna käyttäen API-käyttäjätunnusta ja -salasanaa
  • POST-metodilla
  • antaen pyynnön vartalona (HTTP form datana) kenttä grant_type=client_credentials

Onnistuneen pyynnön vastauksena palautuu JSON-objekti joka sisältää autorisaatiotokenin ja tiedon siitä, kuinka monta sekuntia token on voimassa (tällä hetkellä 3600, eli yksi tunti).

Esimerkki stg-ympäristöön tehtynä:

> curl -X POST -u "käyttäjätunnus:salasana" \
       -d "grant_type=client_credentials" \
       "https://auth.stg.velho.vayla.fi/oauth2/token"

{"access_token":"eyJr... ...Pln4w",
 "expires_in":3600,
 "token_type":"Bearer"}       

Autorisoidun rajapintapyynnön tekeminen

Autentikaatiotoken tulee lisätä kaikkiin rajapintakutsuihin Authorization -headerissa. Header on muotoa Authorization: Bearer <access_token>

Esimerkki:

curl -H "Authorization: Bearer eyJr… …Pln4w" "https://api-v2.stg.velho.vayla.fi/"

Käyttö

Velhon rajapinta koostuu useista erillisistä palveluista, jotka ovat saatavilla rajapinnan juuriosoitteen alla. Rajapinnan juuriosoitteet ovat

  • Staging-ympäristö: https://api-v2.stg.velho.vayla.fi/
  • Tuotantoympäristö: https://api-v2.prd.velho.vayla.fi/

Pyyntö juuriosoitteeseen palauttaa HTML-sivun, joka sisältää linkit palvelukohtaisiin dokumentaatioihin. Erityisesti metatietopalvelun dokumentaatio on syytä käydä läpi.

Tavallisella selaimella pääset selaamaan HTML-pohjaista dokumentaatiota ja Swagger UI:ta esimerkiksi Modheader -selainlaajennosta hyödyntämällä. Laajennos hoitaa tällöin autentikaation lisäämisen tarvittaviin osoitteisiin. Ota huomioon käyttämisi tokenin expiroitumisaika.

Modheader laajennuksen asetukset. (Bearer: *Generoimasi token* URL Pattern: .*:\/\/api-v2..?(stg|prd).velho.vayla.fi.* )

Mikäli haluat lisätä Swagger dokumentaation API:n selailuun tarkoituissa sovelluksissa kuten Postman voit hyödyntää Swaggerin JSON ulostuloa. Osoitteet ovat muotoa :

Latauspalvelu

Latauspalvelu dokumentoidaan tässä, koska siihen ei ole suoraan rajapinnan kautta saatavaa dokumentaatiota.

Latauspalvelu sisältää Velhon (lähes) koko tietosisällön NDJSON-muotoisina tiedostoina. Sitä käytetään kuten muitakin rajapintoja HTTP GET -pyynnöillä.

HTTP-pyynnöt voi tehdä joko hakemistoon (polku päättyy / -merkkiin) tai yksittäiseen tiedostoon (polku päättyy json-muotoiseen tiedostonnimeen).

Hakemistopolkuun tehty pyyntö palauttaa JSON-objektina listan hakemiston alihakemistoista ja/tai sen sisältämistä tiedostoista. Tiedostopolkuun tehty pyyntö palauttaa lyhyen aikaa voimassaolevan uudelleenohjauksen (HTTP 307) varsinaiseen tiedostoon.

Esimerkkejä hakemistolistauksista:

> curl --compressed -H "Authorization: Bearer eyJr.....9coA" \
          https://api-v2.stg.velho.vayla.fi/latauspalvelu/
["2020-08-31/", 
 "2020-09-01/", 
 "2020-09-02/", 
...
 "viimeisin/"] 
> curl -H "Authorization: Bearer eyJr.....9coA" \
          https://api-v2.stg.velho.vayla.fi/latauspalvelu/viimeisin/urakka/
["viimeisin/urakka/maanteiden-hoitourakka.json", 
 "viimeisin/urakka/muu-urakka.json", 
 "viimeisin/urakka/palvelusopimus.json"]

Esimerkki tiedoston lataamisesta (ilman HTTP 307 -uudelleenohjauksen automaattista seuraamista):

> curl -D - -H "Authorization: Bearer eyJr.....9coA" \
          https://api-v2.stg.velho.vayla.fi/latauspalvelu/viimeisin/urakka/palvelusopimus.json
HTTP/2 307 
date: Wed, 28 Oct 2020 16:21:58 GMT
content-length: 0
location: https://s3.eu-central-1.amazonaws.com/latauspalvelu.stg.velho.vayla.fi/viimeisin/urakka/palvelusopimus.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...
...

Tekemällä pyyntö (manuaalisesti tai automaattisesti, riippuen käytetystä HTTP-asiakasohjelmasta) palautuneeseen location-osoitteeseen voi ladata varsinaisen tiedoston:

> curl --compressed --output /tmp/palvelusopimus.json \
       "https://s3.eu-central-1.amazonaws.com/latauspalvelu.stg.velho.vayla.fi/viimeisin/urakka/palvelusopimus.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."       

Hakemistorakenne

Latauspalveluun tuotetaan tiedostot päivittäin, ja tiedostot organisoidaan päiväyksen, nimiavaruuden ja kohdeluokan mukaisesti. Uusin versio kustakin tuotetusta tiedostosta tallennetaan lisäksi viimeisin -haaran alle.

/latauspalvelu/viimeisin/rakennetiedot/pintaukset.json
/latauspalvelu/viimeisin/rakennetiedot/sidotut-paallysrakenteet.json
/latauspalvelu/viimeisin/aineisto/aineisto.json
/latauspalvelu/2020-01-02/rakennetiedot/pintaukset.json

Osa kohdeluokista jakautuu useaan tiedostoon, koska yhtenä tiedostona niistä tulisi liian suuria. Tällöin kohdeluokan nimi toimii hakemistona, ja data on (yleensä tieosan ja kaistan perusteella) pilkottuina tiedostoina sen alaisuudessa.

Esimerkki PTM10 -mittauksista:

> curl -H "Authorization: Bearer eyJr.....9coA" \
          https://api-v2.stg.velho.vayla.fi/latauspalvelu/viimeisin/mittaustiedot/palvelutason-mittaus-pituusprofiili-10m/
["viimeisin/mittaustiedot/palvelutason-mittaus-pituusprofiili-10m/9-213-21.json", 
 "viimeisin/mittaustiedot/palvelutason-mittaus-pituusprofiili-10m/9-214-11.json", 
 "viimeisin/mittaustiedot/palvelutason-mittaus-pituusprofiili-10m/9-214-12.json"]

Tiedostomuoto

Latauspalveluun tuotetaan tiedostot newline delimited JSON -muodossa, jossa kukin rivi sisältää yhden JSON-objektin (joka vastaa yhtä kohde-objektia).

Jokaisen tiedoston ensimmäinen objekti on kuitenkin edellisestä poiketen erillinen metatieto-objekti:

{"paivays":"2020-01-02",
 "kohdeluokka":"rakennetiedot/pintaukset",
 "velho-ymparisto":"stg",
 "luotu":"2020-01-02T15:43:58.017"}

Huom! Yllä kuvattu metatieto-objekti tulee todennäköisesti poistumaan latauspalvelussa tarjottavasta datasta. Toteutukset tulee tehdä siten, että ne toimivat sekä metatieto-objektin kanssa että ilman sitä.

Kohteet vastaavat ulkoisen APIn kautta saatavia kohteita. Tämä pätee myös niiden sisältämien nimikkeistöviittauksien osalta, jotka esiintyvät vain avaimina (esim. pintauksen-tyyppi/pintaus01). Mikäli latauspalvelun käyttäjä tarvitsee nimikkeistöjen selväkielisiä arvoja tai muuta niihin liittyvää tietoa, ne täytyy hakea metatietopalvelun kautta.

Tiedostot tallennetaan gzip-kompressoituina (ja niille asetetaan vastaava Content-Encoding -metatietoattribuutti), jolloin niiden lataaminen ja säilytys on tehokasta. Kompressio on APIn loppukäyttäjille yleensä läpinäkyvää, mutta jotkin HTTP-kirjastot tai -clientit eivät välttämättä suoraan osaa (tai tajua) purkaa gzip-kompressoituja tiedostoja. (Esim. curl vaatii --compressed -komentoriviparametrin.)


Hakupalvelu

Hakupalvelun ohjesivu rajapintakäyttäjille

Liity rajapintakäyttäjien postituslistalle

Postituslistan kautta tiedotetaan ajankohtaisista asioista, joista integraatiokumppaneiden on hyvä olla tietoinen, esim. käyttökatkot tai isommat muutokset.