Tekniset linjaukset
Rajapinta on REST-tyyppinen rajapinta, joka tarjoaa url-kohtaisesti kaikille pyytäjille saman todennäköisesti cachetun JSON-muotoisen tietosisällön.
- Kaikki palvelinpään taustajärjestelmästä noutama tietosisältö cachetaan HTTP-request -tasolla (server side caching). Peräkkäiset eri clienttien samaan URL:ään suorittamat noudot tulevat siis aina front-side cachesta.
- Cache-ajat tietenkin vaihtelevat. Skaala on SIRI-VM viestien kahden sekunnin max-age:sta GTFS-vastauksiin, jotka ovat periaatteessa ikuisia.
- Client-päästä tehtyjä kyselyjä ei voi näin ollen parametroida tai ohjata palvelinta palauttamaan asiakaskohtaisesti muotoiltuja yksilöllisiä tuloksia.
- Perusteena on palvelinkuorman rajoittaminen. Lajittelut, suodatukset ja poiminnat on skaalautumisen kannalta järkevintä tehdä päätelaitteessa itsessään, yhden yhteisen keskitetyn pullonkaulan sijaan.
- Palvelin palauttaa lajittelematonta sisältöä ellei URL:n dokumentaatiossa selvästi sanota, että tulokset palautetaan tietyssä järjestyksessä. Siis - vaikka esimerkiksi pysäkit näyttäisivät tuloksessa olevan aakkosjärjestyksessä, ne eivät sitä välttämättä jatkossa ole, ellei dokumentaatio sitä lupaa. Lajittelu on kokonaisuuden kannalta skaalautuvinta tehdä päätelaitteessa itsessään ellei oletettu lajittelutarve ole todennäköisesti kaikilla kysyjillä sama.
Clientin on tuettava gzip pakkausta HTTP-siirtokerroksella.
- Palvelinpää käyttäytyy aina kuin Accept-encoding sisältäisi "gzip":n. Vastaus tulee pakattuna, pyydettiin tai ei.
- Tällä ehdottomalla vaatimuksella sekä säästetään tietoliikennekaistaa, että vältetään tiedon cacheaminen (ja tuottaminen) erikseen sekä pakkaamattomana, että pakattuna.
- Selaimet ja käytännössä kaikki yleisimmät käyttökelpoiset client-frameworkit / libraryt (Java, JS, PHP, curl, node.js, jne.) tekevät ja toimivat oikein automaattisesti, eikä tätä vaatimusta tarvitse millään tavoin huomioida.
Clientin tulisi käyttää yksilöivää User-Agent -headeria, mikäli mahdollista.
- User-agent -tiedoista olisi toivottavaa tunnistaa sovelluksen nimi, käyttöalusta ja linkki lisätietoihin.
MyApp/1.0.1; (Android/*; +http://mysite.fi/MyApp; info@mysite.fi)
- Tietoa käytetään pääsääntöisesti sisäiseen seurantaan. Mielenkiinnon kohteena on esimerkiksi, mitä sovelluksia käytetään ja mitä yleensäkään on olemassa. Käyttötilastot saattavat jossain vaiheessa olla julkisia, mutta voit lisätä User-agent -headeriin yksiselitteisesti grepattavan merkinnän no-public mikäli et halua tietoa julkiseksi. Esim :
MyTestApp/1.0.1; (Android/*; +http://mysite.fi/MyApp; oma@osoite.fi; no-public)
- WWW-selaimia User-agent -toive ei tietenkään koske. Nämä voidaan erotella Referer-headerista.
Rajapinnassa on rajoitus yksittäisen clientien tekemiin kyselyihin per minuutti.
- Tämän hetken rajoitus on max 32 req/s, 64 req ensipurskeella per ip-osoite. Varsinkin GTFS-requestien suhteen omissa sovelluksissa kannattaa mahdollisuuksien mukaan cacheta vastauksia myös paikallisesti, sillä kaikki GTFS-vastaukset ovat cachettavia.
- Palvelin lähettää url-kohtaisesti sopivat Cache-Control- ja Expires -headerit, joten selaimet tekevät tämän automaattisesti, mutta kännykkäsovelluksissa tästä täytyy huolehtia itse. Käytännössä kannattaa siis kännykkäsovelluksessa varmistaa, että http-client cacheaa, esim (HttpURLConnection / HttpResponseCache)
- Kyselykuorman rajoittamiseksi on mahdollista käyttää myös omaa edustapalvelinta, jolle oman sovelluksen tuottamat kyselyt ohjataan. Käytännössä tämä edustapalvelin on siis yksinkertainen www-proxy.
Kyselyrajapinta on tarkoitettu käytettäväksi HTTP-GET -kyselyin
Rajapinta on käytettävissä sekä SSL, että Ei-SSL yhteydellä.
- Kuorman rajoittamiseksi ja TCP-yhteyden kättelyn nopeuttamiseksi toivottavaa olisi kuitenkin käyttää Ei-SSL -yhteyttä, ellei pakottavaa tarvetta SSL:n käyttämiseen ole.