Käyttöliittymäkirjautuminen tapahtuu samalla tavoin extranet-tunnuksin kuin aiemmin, rajapintojen käyttöön tarvitaan API-tunnukset, jotka ovat organisaatiokohtaiset.
Ympäristöjen osoitteet ovat:
Velho-tuotanto: https://velho.vaylapilvi.fi/
Velho-stg: https://velhostaging.testivaylapilvi.fi/
Rajapintapalveluiden dokumentaatiot
Palveluiden ohjeet ja dokumentaatiot rajapintakäyttäjiltä löytyvät allaolevien linkkien kautta (toimivat extranet-kirjautumisella)
- Metatietopalvelu
- Latauspalvelu
- Hakupalvelu
- Lähetyspalvelu
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
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 ja organisaation sisällä tunnuksia voi käyttää useampi henkilö. MIkäli tarvitsette rajapintatunnuksia, olkaa yhteydessä Velhotukeen (velhotuki@vayla.fi)
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
- DEV-ympäristö https://vayla-velho-dev.auth.eu-west-1.amazoncognito.com/oauth2/token
- Staging-ympäristö https://vayla-velho-stg.auth.eu-west-1.amazoncognito.com/oauth2/token
- Tuotantoympäristö https://vayla-velho-prd.auth.eu-west-1.amazoncognito.com/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://vayla-velho-stg.auth.eu-west-1.amazoncognito.com/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://apiv2stgvelho.testivaylapilvi.fi"Käyttö
Velhon rajapinta koostuu useista erillisistä palveluista, jotka ovat saatavilla rajapinnan juuriosoitteen alla. Rajapinnan juuriosoitteet ovat
- DEV-ympäristö: https://apiv2devvelho.testivaylapilvi.fi
- Staging-ympäristö: https://apiv2stgvelho.testivaylapilvi.fi
- Tuotantoympäristö:
https://apiv2prdvelho.vaylapilvi.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.