Rajapinta
VRL:n rajapinnan kautta voit hakea ja näyttää omilla sivuillasi ajantasaisia tietoja suoraan VRL:n rekistereistä. Edellytyksenä on php:n tai muun vastaavan ohjelmointikielen käyttömahdollisuus. Rajapinta palauttaa tiedot json-muodossa.
Rajapinnan käyttö
Alla on esimerkki rajapinnan käyttöönotosta PHP-koodilla. Allaolevan koodin suorituksen jälkeen json-muotoinen data on $obj nimisessä PHP arrayssa, jota voit käsitellä kuten normaalia PHP Arrayta
$url = 'http://rajapinnan osoite parametreineen';
$obj = json_decode(file_get_contents($url), true);
Esimerkkihakuja tekemällä näet mitä sisältöjä rajapinnasta tulee. Rajapintoja voidaan muokata jälkikäteen, mutta muokkaukset eivät muuta olemassaolevia kenttiä tai niiden järjestystä. Kenttiä voi kuitenkin tulla lisää. Tee siis toteutuksesi siten, että mahdolliset uudet kentät eivät vaikuta siihen!
Mikäli rajapintakutsu onnistuu, paluuarvo on suunnilleen tämän muotoinen:
{"error":0,"rajapinnan nimi":["rajapinnan","palauttama","sisalto","taulukkona"]}
Onnistunut tulos sisältää aina error kentän jonka arvo on 0. Virheviesti sisältää error kentän jossa on arvo 1. Lisäksi viestissä on mukana virhekoodi ja virheen sanallinen kuvaus.
Mikäli rajapintakutsussa tapahtuu virhe tai tuloksia ei löydy, paluuarvo on tämän näköinen.
{"error":1,"error_code":"Virhekoodi numerona","error_description":"Virheen sanallinen kuvaus"}
Virhekoodit
- 400: Antamasi parametri (esim. vh-tunnus tai kilpailun id) on virheellinen
- 404: Antamillasi parametreilla (esim. vh-tunnus tai kilpailun id) ei löydy tulosta
- 600: Porrastetut: Hevonen liian nuori tai siltä puuttuu ikä.
- 601: Porrastetut: Hevonen liian matala tai siltä puuttuu säkäkorkeus.
- 800: Tapahtui odottamaton virhe. Ota yhteys ylläpitoon.
Rajapinnat
Tällä komennolla saat valitsemasi kilpailun tulos-id:n ja tulosarkistosivun osoitteen
Esimerkkihaku: https://virtuaalihevoset.net/rajapinta/nayttelytulos_id/3240/Haetaan tietyn kasvattajanimen kasvatit, parametrina kasvattajanimen id, ja halutessaan valitun rodun id. Rodun id:n antaminen ei ole pakollista. Ilman ID:tä haetaan kaikenrotuiset kasvatit.
Esimerkkihaku: https://virtuaalihevoset.net/rajapinta/nimenkasvatit/2047/28/Tällä komennolla voit hakea valitsemasi hevosen porrastettujen ominaisuuspisteet ja tason. HUOM! tämä on vanhentunut, ja käsittää vain neljä alkuperäistä porrastettujen jaosta. Toimii samalla tavalla kuin vanha "ominaisuudet" rajapinta, mutta vanha rakenne on nyt uuden rajapintarakenteen mukaisesti "ominaisuudet" kentässä. Virhekoodit vastaavat vanhaa, eivätkä uutta rajapintaa. Älä ota tätä käyttöön mikäli teet sivuillesi uutta toteutusta! Käytä "porrastetut"-rajapintaa tämän sijaan.
Esimerkkihaku: https://virtuaalihevoset.net/rajapinta/ominaisuudet/VH03-028-8756/Tällä komennolla voit hakea valitsemasi hevosen porrastettujen ominaisuuspisteet ja tason kaikissa jaoksissa ja ominaisuuksissa. Koska jaoksia ja ominaisuuksia voi tulla lisää, rajapinta palauttaa myös tiedot jaoksista ja ominaisuuksista. Rajapinta palauttaa myös hevosen ikä- ja säkäkorkeustiedot sekä VRL:n sivuilla asetetun maksimitason.
Esimerkkihaku: https://virtuaalihevoset.net/rajapinta/porrastetut/VH03-028-8756/Esimerkkikoodi: Esimerkkikoodi Githubissa
Haetaan tietyn tallin kasvatit, parametrina tallin tallitunnus, ja halutessaan valitun rodun id. Rodun id:n antaminen ei ole pakollista. Ilman ID:tä haetaan kaikenrotuiset kasvatit.
Esimerkkihaku: https://virtuaalihevoset.net/rajapinta/tallinkasvatit/KARK4835/28/Tällä komennolla saat valitsemasi kilpailun tulos-id:n ja tulosarkistosivun osoitteen
Esimerkkihaku: https://virtuaalihevoset.net/rajapinta/tulos_id/153969/Tällä komennolla voit hakea valitsemasi hevosen jälkeläiset.
Esimerkkihaku: https://virtuaalihevoset.net/rajapinta/varsat/VH03-028-8756/Esimerkkikoodi: Esimerkkikoodi Githubissa