Tämä sivu on tarkoitettu Projektivelhon rajapintakäyttäjille, ketkä hakevat tietoa Projektivelhosta, luovat tietoa Projektivelhoon tai päivittävät Projektivelhon tietoja rajapintojen kautta.
Projektivelhon tietorakenne
Velho-järjestelmän tietorakenne koostuu taustapalveluista eli eri rekistereistä ja palveluista. Rekisterit ja palvelut voivat koostua yhdestä tai useammasta tietokokonaisuudesta sekä niihin kuuluvista kohdeluokista. Projektivelhossa hallittavat tiedot ovat sekä projektirekisterissä että aineistopalvelussa. Molempiin taustapalveluihin kuuluu yksi tietokokonaisuus. Tietokokonaisuudesta käytetään swagger-dokumentaatioissa termiä ”nimiavaruus”. Kohdeluokkien tekniset nimet muodostuvat seuraavalla tavalla: <nimiavaruus>/<kohdeluokka>. Esimerkiksi projektirekisteriin kuuluvan ”Toimeksianto”-kohdeluokan tekninen nimi on projekti/toimeksianto. Kohdeluokkien tekniset nimet näkyvät rekistereiden swagger-dokumentaatioissa (linkit luvussa ”REST-api rekisterirajapinnat”).
Projektirekisteriin kuuluu ”projekti”-tietokokonaisuus, joka koostuu seuraavista kohdeluokista:
- projektijoukko
- projekti
- toimeksianto.
Näistä käytetään Projektivelhossa yleistermiä ”hanketiedot”.
Aineistopalveluun kuuluu ”aineisto”-tietokokonaisuus, joka koostuu seuraavista kohdeluokista:
- aineisto
- dokumentti
- ladattava paketti
- pakattu kansio
- viittaus.
Tietokuvaus
Velhon tietokuvauksessa tietorakenne on jaoteltu tietokokonaisuuksittain. Projektivelhon kohdeluokkien tietosisältö löytyy siis ”aineisto” ja ”projekti” -tietokokonaisuuksien alta. Loput tietokokonaisuudet ovat Tievelhoon kuuluvia tietokokonaisuuksia. Tietokuvauksesta löytyy jokaisen kohdeluokan tietosisältö sekä tieto kenttien (avainten) pakollisuudesta ja kentän arvon tietotyypistä. Arvot voivat olla tietotyypiltään merkkijonoja, lukuja, totuusarvoja, avainluetteloita tai nimikkeistöjä. Nimikkeistö on kentälle annettava arvojoukko.
Rajapinnat
Projektivelhon tietosisältöä hyödynnetään useissa eri ulkoisissa järjestelmissä ja myös päivitetään ulkoisten järjestelmien kautta. Ulkoisten rajapintojen käyttöohjeesta löytyy yleiset ohjeet Velhon rajapintojen käyttöön, kuten autentikointiin.
Projektivelhon tietosisältö on hyödynnettävissä Latauspalvelun, Hakupalvelun tai rekistereiden suoran REST-api rajapinnan kautta. Metatietopalvelu tarjoaa kuvauksen Projektivelhon tietosisällöstä.
Latauspalvelu
Latauspalvelusta on ladattavissa etukäteen tuotettuja tietosisältöjä Velhossa hallittavista kohdeluokista ndjson-muodossa. Sen tarkoitus on tarjota tehokas tapa massatiedon käsittelyyn Velhon ulkopuolella. Reaaliaikaisen tai tarkemmin rajatun tiedon hakemiseen suositellaan Hakupalvelua tai Velhon perusrekistereitä. Latauspalveluun tuotetaan tietosisällöt kerran vuorokaudessa aamuyöllä n. klo 03-04.
Latauspalvelussa kukin kohdeluokka on rajattu ELY-keskusten liikenne- ja infrastruktuurivastuualueiden jaottelun (ELY L-aluejako) mukaisesti. Projektille mahdollisesti tallennettu tieosoite/tieosoitteet määrittävät, mille ELY L-alueelle projekti kuuluu. Mikäli tieosoite/tieosoitteet osuvat useammalle ELY L-alueelle, projekti tuotetaan kaikkien kyseenomaisten alueiden lataustiedostoihin. ELY L-alueiden yksilöintiin käytetään alueet/ely -nimikkeistöä, joka on saatavilla metatietopalvelusta. Tästä nimikkeistöstä kaikki nimikkeet eivät ole L-aluejaossa mukana. ELY L-aluejako on seuraava:
Mikäli projektilla ei ole tieosoitetta, projekti tuotetaan jaotteluavaimella ”maarittelematon” luokiteltuun lataustiedostoon.
Latauspalvelun dokumentaatio: https://velho.vaylapilvi.fi/latauspalvelu/public/index.md
HUOM! Projektivelhossa käytetään vielä Latauspalvelun ”vanhaa versiota” noin vuoden 2024 loppuun asti. Tässä versiossa kohteet menevät indeksoinnin kautta Latauspalveluun. Mikäli kohteen indeksoinnissa tapahtuu virhe, kohdetta ei löydy Latauspalvelusta. Olethan yhteydessä Projektivelhon tukeen (projektivelho@vayla.fi), mikäli Projektivelhossa olevaa kohdetta (esim. projektia) ei löydy Latauspalvelun kautta. Tunnistettuja ongelmia indeksoinnissa ovat erilaiset projektin geometriaan (sijaintiin) liittyvät haasteet. Uuden Latauspalvelun käyttöönotosta tiedotetaan erikseen Projektivelhon rajapintakäyttäjiä.
Hakupalvelu
Hakupalvelu mahdollistaa hakujen tekemisen koko Velhon tietosisällöstä. Muut palvelut ja rekisterit tarjoavat omissa rajapinnoissaan rajoittuneemmat hakutoiminnallisuudet. Hakupalveluun tuotetaan tietosisällöt kerran vuorokaudessa aamuyöllä n. klo 03-04.
Hakupalvelun dokumentaatio: https://velho.vaylapilvi.fi/hakupalvelu/public/index.md
HUOM! Velhon kohteet menevät tällä hetkellä indeksoinnin kautta Hakupalveluun. Mikäli kohteen indeksoinnissa tapahtuu virhe, kohdetta ei löydy Hakupalvelusta. Olethan yhteydessä Projektivelhon tukeen (projektivelho@vayla.fi), mikäli Projektivelhossa olevaa kohdetta (esim. projektia) ei löydy Hakupalvelun kautta. Tunnistettuja ongelmia indeksoinnissa ovat erilaiset projektin geometriaan (sijaintiin) liittyvät haasteet.
REST-api rekisterirajapinnat
REST-api rajapinnat tarjoavat toiminnallisuuksia kohteiden hakuun, luontiin, päivittämiseen ja poistamiseen. Velhon rajapintojen yleisissä toimintaperiaatteissa on kerrottu Velhon rekistereiden toiminnallisuuksista yleisesti. Suurin osa ohjeistuksesta koskee Tievelhon perusrekistereitä. Tämän sivun luvussa ”Rajapintojen käyttö” on kerrottu projektirekisterin ja aineistopalvelun REST-api rajapintojen käytöstä.
Velhon rajapintojen yleiset toimintaperiaatteet: https://velho.vaylapilvi.fi/projektirekisteri/public/rajapinnat.md
Projektirekisterin Swagger-dokumentaatio: https://velho.vaylapilvi.fi/projektirekisteri/doc/v2/swagger/index.html
Aineistopalvelun Swagger-dokumentaatio: https://velho.vaylapilvi.fi/aineistopalvelu/doc/v1/swagger/index.html
Metatietopalvelu
Metatietopalvelu on keskitetty auktoriteetti muiden palveluiden ja rekisterien hallinnoiman tietosisällön muodolle. Se tarjoaa kuvauksen Velhon tietosisällöstä eli metatiedoista OpenAPI 3 -standardimuodossa Velhoon integroituvia tai tietosisältöä muuten hyödyntäviä järjestelmiä varten.
Metatietopalvelun dokumentaatio: https://velho.vaylapilvi.fi/metatietopalvelu/public/index.md
Rajapintojen käyttö
Tietojen hakeminen
Projektivelhon tietosisältöä pystyy hakemaan Latauspalvelun, hakupalvelun ja suoran REST-api rekisterirajapinnan kautta. Tiivistettynä erot tietojen haussa eri rajapintojen välillä ovat seuraavat:
- Latauspalvelu tarjoaa tehokkaan tavan massatiedon käsittelyyn Velhon ulkopuolella. Tiedot päivittyvät Latauspalveluun kerran vuorokaudessa. Mahdolliset ongelmat indeksoinnissa vaikuttavat siihen, mitä kohteita Latauspalveluun menee. Latauspalvelu palauttaa kohteet ndjson-muodossa. Latauspalvelu palauttaa projekti-kohdeluokalla mahdollisten tie- ja rataosoitteiden koordinaatit, mikä saattaa tehdä JSON-objektista isokokoisen.
- Hakupalvelu mahdollistaa monimutkaiset hakulausekkeet yli koko Velhon tietosisällön. Tiedot päivittyvät Hakupalveluun kerran vuorokaudessa. Mahdolliset ongelmat indeksoinnissa vaikuttavat siihen, mitä kohteita Hakupalveluun menee. Hakupalvelu ei palauta kohteiden tietoja täydellisesti, ainoastaan hakulausekkeessa määritellyt tietokentät.
- REST-api rekisterirajapinnat tarjoavat suoran yhteyden Velhon rekistereihin. Tieto on ajantasaista. Rekisterirajapinnat palauttavat kohteet ndjson-muodossa. Projektirekisterin rekisterirajapinta palauttaa oletuksena projekti-kohdeluokalla mahdollisten tie- ja rataosoitteiden koordinaatit, mutta ne on mahdollista jättää JSON-objektista pois query parametrin avulla (tarkemmat ohjeet alla REST-api rekisterirajapinta > Kohteen haku tunnisteen avulla -kohdassa).
Hakiessa tiedot palautuvat aina uusimman skeemaversion mukaisina.
Latauspalvelu
Latauspalvelu tarjoaa rajapinnat
- saatavilla olevien kohdeluokkakohtaisten sisältöjen luettelointiin (rajapinta kohdeluokat)
- yksittäisen kohdeluokan sisältökuvauksen hakemiseksi (rajapinta kohdeluokka)
- kohdeluokkakohtaisen, ELY-jaotellun lataustiedoston hakemiseksi (rajapinta kohteet).
Rajapintakutsut näet Latauspalvelun Swagger-dokumentaatiosta.
Rajapinta kohdeluokat listaa Latauspalvelussa saatavilla olevat kohdeluokat.
Rajapinta kohdeluokka palauttaa kuvauksen kohdeluokan ladattavissa olevasta tietosisällöstä. Kuvaus sisältää tiedon kohteiden jaottelusta ELY L-aluejaon mukaisesti, kohteiden lukumäärästä kussakin lataustiedostossa sekä ajanhetkestä, jolloin sisältö on tuotettu Latauspalveluun.
Rajapinta kohteet palauttaa annetun kohdeluokan kohteet ndjson-muodossa siten, että tiedoston jokainen rivi on itsenäinen, validi JSON-objekti. Kutsu tuottaa HTTP 307 -redirectin, eikä sitä voi sen takia käyttää Swagger-käyttöliittymässä. Jaotteluna on ELY L-aluejako, esimerkiksi ely/ely10 tai ely/maarittelematon.
HUOM! Tiedostoja ladattaessa ns. tarkka TLS-validointi (strict TLS validation) on mahdollisesti kytkettävä pois päältä, mikäli käytettävä työkalu tai kirjasto sitä käyttää. Tämä on Latauspalvelun taustalla toimivan järjestelmän tekninen rajoite, ja yhteys on tästä huolimatta turvallinen. Esim. curl -työkalulla tämä tapahtuu antamalla -k tai --insecure -komentoriviparametri.
Hakupalvelu
Hakupalvelu tarjoaa sekä kohdennettuja hakutoiminnallisuuksia esimerkiksi aineistojen hakemiseen, että yleiskäyttöiset lausepohjaiset kohdeluokka- ja tieosuushakutoiminnot koko Velhon tietosisällöstä hakemiseen. Kohdeluokkahaku kohdistuu yhteen tai useampaan kohdeluokkaan, ja palauttaa annettuja kriteereitä vastaavat kohteiden tiedot. Haettavien kohdeluokkien rakenne vastaa metatietopalvelussa määriteltyjä kohdeluokkia. Hakupalvelu ei palauta kohteita ndjson-muodossa, vaan ainoastaan kyselyssä annettavassa JSON-objektissa erikseen määritetyt kentät.
Rajapintakutsut näet Hakupalvelun Swagger-dokumentaatiosta.
Hakupalveluun tehtävä kysely annetaan JSON-objektina. Ohjeet hakulausekkeen muodostamiseen on esitetty Hakupalvelun dokumentaatiossa.
REST-api rekisterirajapinnat
Jokainen Velhon perusrekisteri tarjoaa REST-api-rajapinnat, joista pystyy reaaliaikaisesti hakemaan Velhon tietosisältöä. Alla on kuvattu eri kyselyt kohteiden hakuun projektirekisterissä ja aineistopalvelussa (koskee aineistojen metatietoja ja viittauksia). Dokumenttien (tiedostojen) lataus rajapinnan kautta S3 bucketista sekä tiedostojen vienti rajapinnan kautta S3 bucketiin ohjeistetaan myöhemmin.
Tunnisteiden (OID:ien) haku
GET /projektirekisteri/api/v2/tunnisteet/{nimiavaruus}/{kohdeluokka}
GET /aineistopalvelu/api/v1/tunnisteet/{nimiavaruus}/{kohdeluokka}
Palauttaa annetun kohdeluokan kohteiden tunnisteet (OID:t) JSON-array:na. Hakua voi rajata muokkausaikavälillä (kohteiden JSON-objektissa oleva ”muokattu”-kenttä) asettamalla date-time string -tyyppiset query parametrit ”alkumuokkausaika” ja/tai ”loppumuokkausaika”.
Kohdeluokan kaikkien kohteiden haku
GET /projektirekisteri/api/v2/{kohdeluokka}
GET /aineistopalvelu/api/v1/{kohdeluokka}
Palauttaa annetun kohdeluokan kohteet ndjson-muodossa yhdellä rivillä. Projekti-kohdeluokalla rajapinta palauttaa kohteet ilman projektille asetettujen sijaintien koordinaatteja. Rajapinta ei ole käytössä toimeksianto-kohdeluokalla.
Kohteen haku tunnisteen avulla
GET /projektirekisteri/api/v2/{kohdeluokka}/{oid}
GET /aineistopalvelu/api/v1/{kohdeluokka}/{oid}
Palauttaa annetun kohteen tiedot ndjson-muodossa. Boolean-tyyppisellä query parametrilla ”ei-geometrioita” arvolla ”true” voi jättää projekti-kohdeluokalla vastaussanomasta sijaintien koordinaatit pois, mikä pienentää vastauksen kokoa. Etenkin rataosoitteiden geometriat saattavat olla hyvin pitkiä ja koordinaatit kannattaa jättää vastaussanomasta pois, mikäli vastaanottava järjestelmä ei niitä tarvitse.
Tietojen päivittäminen
Projektivelhon kohteiden tietoja pystyy päivittämään REST-api rajapinnan kautta PUT-metodilla. Päivityksessä pyyntönä on kohteen validi JSON-objekti sisältäen muuttuneet tiedot. HUOM! Myös muuttumattomat kentät lähetetään JSON-objektissa, ei pelkästään muuttuneita tietoja. Päivitettävän kohteen OID-tunnus välitetään sekä JSON-objektissa, että rajapintakyselyssä.
Osa kohdeluokille annettavista tietokentistä on pakollisia ja osa valinnaisia. Kentän pakollisuuden näkee Velhon tietokuvauksesta. Pakolliset kentät tulee olla aina mukana JSON-objektissa tietojen päivityksessä. Valinnaisia kenttiä ei tarvitse lähettää JSON-objektissa. Tietojen häviämisen välttämiseksi päivitys suositellaan kuitenkin tehtävän siten, että
- kohteen tiedot haetaan ensin GET-metodilla REST-apin kautta (kts. edellinen luku ”Tietojen hakeminen”),
- haettua JSON-objektia muokataan päivittyneillä tiedoilla (kenttä lisätään tai kentän arvoa muutetaan),
- muokattu JSON-objekti lähetetään PUT-metodilla REST-api rajapintaan.
Päivitykset tehdään tällöin aina uusimman skeemaversion mukaisesti ja päivityssanoma sisältää kaikki kohteen tiedot (mukaan lukien valinnaiset kentät).
HUOM! Pyyntöjä kannattaa lähettää yksi kerrallaan, koska järjestelmä ottaa useamman pyynnön käsittelyyn samanaikaisesti, mikäli niitä lähetetään useampi. Tämä saattaa johtaa rajapinnan palauttamaan virheeseen. Yleisimmät virheet valideissa päivityspyynnöissä ovat 502 Bad Gateway ja 504 Gateway Timeout. Mikäli virhe on 502, päivityspyyntö ei ole mennyt läpi ja päivitystä kannattaa yrittää uudelleen. Mikäli virhe on 504, päivityspyyntö on saattanut mennä läpi, mutta client ei ole kerennyt saamaan rajapinnan kautta vastaussanomaa onnistuneesta päivityksestä. 504 virhekoodin saaneet päivityspyynnöt tulee aina tarkastaa, ovatko ne menneet läpi ja sen jälkeen yrittää päivitystä uudelleen, mikäli päivitys ei ole mennyt läpi. Lisätietoja yleisimmistä virhevastauksista on tämän sivun luvussa ”Yleisimmät rajapinnan palauttamat virheet”.
Onnistuneen päivityksen vastauksena on päivitetty kohde ndjson-muodossa. Lisätietoja päivityssanomassa olevan JSON-objektin validoinnista on tämän sivun luvussa ”Tiedon validointi”.
Projektijoukkojen päivitys
PUT /projektirekisteri/api/v2/projektijoukko/{oid}
Päivittää projektijoukon tiedot. Pyyntönä lähetetään kohteen kaikki tiedot päivitetyillä arvoilla JSON-objektina.
Projektien päivitys
PUT /projektirekisteri/api/v2/projekti/{oid}
Päivittää projektin tiedot. Pyyntönä lähetetään kohteen kaikki tiedot päivitetyillä arvoilla JSON-objektina. JSON-objektiin ei kannata sisällyttää mahdollisia projektien sijaintien koordinaatteja, koska järjestelmä ei niitä päivityksessä tarvitse. Liian suuret geometriat voivat aiheuttaa ”413 Request Entity Too Large” -virheen eikä päivityspyyntö mene läpi. Query parametrilla ”ei-geometrioita=true” voidaan jättää sijaintien koordinaatit pois vastaussanomasta GET- ja PUT-metodeilla.
Toimeksiantojen päivitys
PUT /projektirekisteri/api/v2/toimeksianto/{oid}
Päivittää toimeksiannon tiedot. Pyyntönä lähetetään kohteen kaikki tiedot päivitetyillä arvoilla JSON-objektina.
Aineistojen metatietojen päivitys
PUT /aineistopalvelu/api/v1/aineisto/{oid}
Päivittää aineiston metatiedot. Pyyntönä lähetetään kohteen kaikki tiedot päivitetyillä arvoilla JSON-objektina.
Tiedon luonti
Projektivelhoon pystyy luomaan uusia kohteita REST-api rajapinnan kautta POST-metodilla. Luonnissa pyyntönä on kohteen validi JSON-objekti.
Osa kohdeluokille annettavista tietokentistä on pakollisia ja osa valinnaisia. Kentän pakollisuuden näkee Velhon tietokuvauksesta. Pakolliset kentät tulee olla aina mukana JSON-objektissa tietojen päivityksessä. Osalle pakollisista kentistä voi antaa arvoksi null. Sallitut arvot ja tietotyypit ovat näkyvissä Velhon tietokuvauksessa. Valinnaisia kenttiä ei tarvitse lähettää JSON-objektissa, ellei niille anneta arvoa.
HUOM! Pyyntöjä kannattaa lähettää yksi kerrallaan, koska järjestelmä ottaa useamman pyynnön käsittelyyn samanaikaisesti, mikäli niitä lähetetään useampi. Tämä saattaa johtaa rajapinnan palauttamaan virheeseen. Yleisimmät virheet valideissa pyynnöissä ovat 502 Bad Gateway ja 504 Gateway Timeout. Mikäli virhe on 502, pyyntö ei ole mennyt läpi ja luontia kannattaa yrittää uudelleen. Mikäli virhe on 504, pyyntö on saattanut mennä läpi, mutta client ei ole kerennyt saamaan rajapinnan kautta vastaussanomaa onnistuneesta luonnista. 504 virhekoodin saaneet pyynnöt tulee aina tarkastaa, ovatko ne menneet läpi, ennen kuin luontia yrittää uudelleen. Koska järjestelmä ei tässä tapauksessa palauta kohdetta ndjson-muodossa, joka sisältäisi luodun kohteen OID-tunnisteen, tarkastus on hankalampaa kuin esimerkiksi päivityksessä, joissa päivitettävien kohteiden OID:t on tiedossa. Tämän vuoksi on tärkeää, että pyynnöt tehdään yksi kerrallaan ja mahdollisesta rajapinnan hitaudesta ilmoitetaan Projektivelhon tukeen projektivelho@vayla.fi. Lisätietoja yleisimmistä virhevastauksista on tämän sivun luvussa ”Yleisimmät rajapinnan palauttamat virheet”.
Onnistuneen luonnin vastauksena on luotu kohde ndjson-muodossa. Järjestelmä generoi kohteelle OID-tunnuksen ja palauttaa sen vastaussanomassa. Lisätietoja pyynnössä olevan JSON-objektin validoinnista on tämän sivun luvussa ”Tiedon validointi”.
Projektijoukkojen luonti
POST /projektirekisteri/api/v2/projektijoukko
Luo uuden projektijoukon. Pyyntönä on kohteen validi JSON-objekti.
Projektien luonti
POST /projektirekisteri/api/v2/projekti
Luo uuden projektin. Pyyntönä on kohteen validi JSON-objekti. Query parametrilla ”ei-geometrioita=true” voidaan jättää sijaintien koordinaatit pois vastaussanomasta.
Toimeksiantojen luonti
POST /projektirekisteri/api/v2/toimeksianto
Päivittää toimeksiannon tiedot. Pyyntönä lähetetään kohteen kaikki tiedot päivitetyillä arvoilla JSON-objektina.
Tiedon poistaminen
Projektivelhon kohteita pystyy poistamaan REST-api rajapinnan kautta DELETE-metodilla. Pyyntöön sisällytettään poistettavan kohteen OID-tunnus. Poiston rajapintakutsut näet taustapalveluiden Swagger-dokumentaatioista.
Tiedon validointi
Projektivelhon kohteiden validointi on toteutettu skeemassa eli Metatietopalvelussa ja/tai koodissa.
Metatietopalvelu (skeema)
Muokkaus- ja luontivarianttien JSON-objektit voi validoida Metatietopalvelun tarjoaman rajapinnan kautta. Metatietopalvelun rajapinta validoi kohteet ainoastaan skeemaan tehtyjen validointien perusteella. Validointikysely on seuraava:
POST /metatietopalvelu/api/v2/validoi/{nimiavaruus}/{nimi}/{variantti}
Kyselyyn annetaan kohteen tekninen nimi sekä variantti (muokkaus vai luonti). Muokkausvariantilla tarkoitetaan kohteen päivitystä. Pyyntönä on validoitava JSON-objekti. Onnistuneen validoinnin tuloksena rajapinta palauttaa kohteesta ns. normalisoidun version, eli saman objektin mutta kentät pakotettuina normaalimuotoihinsa ja ylimääräiset kentät poistettuina.
HUOM! Metatietopalvelu ei validoi virheellisesti kirjoitettuja valinnaisia kenttiä, koska se tulkitsee ne ylimääräisiksi ja poistaa ne. Koska JSON-objekti on validi ilman valinnaisia kenttiä, Metatietopalvelu ei palauta virhettä niiden puuttuessa. Täten luonnin tai päivityksen JSON-objektista saattaa jäädä puuttumaan valinnaisia kenttiä, jos avaimet on väärin kirjoitettu.
Epäonnistuneen validoinnin tuloksena on HTTP virhekoodi 400. Vastaussanomassa on kerrottu virheellinen arvo, sekä mitä sen tulisi skeeman mukaan olla.
Mikäli luonti- tai päivityspyynnössä rajapintaan yrittää lähettää skeeman vastaista JSON-objektia, palautuu HTTP virhekoodi 400 sekä "spec": "(spec-tools.core/spec {:spec (spec-tools.core/spec -alkuinen vastaussanoma, jossa on kerrottu skeeman vastainen virhe JSON-objektissa.
Metatietopalvelun dokumentaatio: https://velho.vaylapilvi.fi/metatietopalvelu/public/index.md
Metatietopalvelun Swagger-dokumentaatio: https://velho.vaylapilvi.fi/metatietopalvelu/doc/v2/swagger/index.html#/
Koodissa olevat validoinnit
Metatietopalvelun lisäksi validointeja on lisätty koodiin. Tällöin virheet eivät jää Metatietopalvelun validoinnissa kiinni.
Mikäli luonti- tai päivityspyynnössä rajapintaan yrittää lähettää koodiin lisätyn validaation vastaista JSON-objektia, palautuu HTTP virhekoodi 400 ja vastaussanoma, johon on lisätty selkeä virheviesti.
Yleisimmät rajapinnan palauttamat virheet
Alla on listattu yleisimmät Projektivelhon rajapintojen käytössä esiintyvät HTTP virhekoodit.
400 Bad Request
Pyyntö on clientin päässä virheellinen (esim. JSON-objekti validointien vastainen), eikä rajapinta pysty käsittelemään pyyntöä.
401 Unauthorized
Käyttäjän tai järjestelmän tulee autentikoitua. Lisätietoja autentikoinnista Ulkoisten rajapintojen käyttöohjeessa.
403 Forbidden
Käyttäjällä tai järjestelmällä ei ole oikeuksia kyseiseen toimenpiteeseen. Ole tarvittaessa yhteydessä Velhon tukisähköpostiin velhotuki@vayla.fi oikeuksien lisäämiseksi.
404 Not Found
Kohdetta ei löydy. Kohde on joko poistettu, tai haettu kohde ei ole kyseisen palvelun vastuulla.
413 Request Entity Too Large
Pyynnössä lähetetty JSON-objekti on liian suuri. Virhe saattaa tulla esimerkiksi silloin, kun päivityspyyntöön on sisällytetty haussa palautuneet sijaintien koordinaatit.
500 Internal Server Error
Sisäinen palvelinongelma. Pyyntö ei ole mennyt läpi ja se kannattaa tehdä hetken kuluttua uudelleen.
501 Not Implemented
Kyseistä metodia ei ole toteutettu.
502 Bad Gateway
Hetkellinen häiriö palvelimella. Pyyntö ei ole mennyt läpi ja se kannattaa tehdä hetken kuluttua uudelleen.
503 Service Unavailable
Palvelin on hetkellisesti pois käytöstä esimerkiksi huoltokatkon vuoksi.
504 Gateway Timeout
Aikakatkaisu. Pyyntö on saattanut virheilmoituksesta huolimatta mennä läpi. Aikakatkaisu saattaa johtua useammasta samanaikaisesta pyynnöstä tai häiriöstä palvelimella. Toistuvista aikakatkaisu-virheilmoituksista tulee ilmoittaa Projektivelhon tukisähköpostiin projektivelho@vayla.fi.