Liity rajapintakäyttäjien postituslistalle

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

Palveluiden dokumentaatiot

Palveluiden dokumentaatiot löytyvät allaolevien linkkien kautta (toimivat extranet-kirjautumisella)

Metatietopalvelu

Metatietopalvelun ohjesivu rajapintakäyttäjille

Latauspalvelu

Latauspalvelun ohjesivu rajapintakäyttäjille

Hakupalvelu

Hakupalvelun ohjesivu rajapintakäyttäjille

Lähetyspalvelu

Lähetyspalvelun ohjesivu rajapintakäyttäjille

Huom! Lähetyspalvelua käytetään tietojen päivittämiseen ja nämä tietohuoltoprosessit käydään päivittäjien kanssa erikseen läpi.

Rajapintojen käyttöohje

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

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 :