TSJL - GTFS -Osoitteistus

REST-linkkien osoitteistus

REST-linkit on versioitu. Tällä hetkellä versio on v0. Joskus - kun nähdään, että nyt on hyvä - versio tulee olemaan v1. Siihen asti sisältö ja käytettävät URL:t saattavat muuttua.
REST-linkkien pohjapolku on http://data.foli.fi/gtfs
REST-linkkeihin on jätetty mahdollisuus osoittaa niitä joko versioituna tai osoittaen uusimpaan versioon. Esim pysäkit on kysyttävissä joko uusimpaan versioon tai tiettyyn versioon osoittaen linkkeinä

Tietokannassa on mahdollisesti useita versioita datasisällöstä. Yllä olevat linkit ovat aina HTTP-302 edelleenohjauksia varsinaiseen sisältöön. Varsinainen sisältö on aina dataset-kohtaisessa url:ssä.

Tällä mahdollistetaan datasisällön pysyvä cacheaminen, että client pään osoittaminen nimenomaan tiettyyn datakokonaisuuteen ("latest" -tyypin linkit saattava muuttua osoittamaan uudempaan versioon)
Selaimet seuraavat linkkejä automaattisesti, useimmissa Client-frameworkeissa on ainakin asetettavan option kautta mahdollisuus komentaa HTTP-302:t automaattisti seurattavaksi.

Lähtökohtaisesti kannattaa käyttää versioimattomia linkkejä. Versio v1 tulee olemaan testausvaiheen jälkeen viimeisin nyt vielä mahdollisesti muuttuvasta versiosarjasta v0.

Linkkien edelleenohjautuminen

Palvelinpään toteutusperiaatteena on, että kaikkien linkkien tulee olla pitkäaikaisesti cachettavia. Tästä syystä lyhyet peruslinkit (kuten http://data.foli.fi/gtfs/agency eivät sisällä varsinaista tietosisältöä vaan ovat edelleenohjauksia varsinaiseen tietosisällön sisältävään URL:ään.

(Lyhyet linkithän eivät voi sisältää tietosisältöä, sillä GTFS-lähdetiedoston muuttuessa myös niiden sisältö muuttuisi, eivätkä ne olisi näin ollen cachettavia.)

Kun client noutaa lyhyen peruslinkin, se saa vastauksena HTTP 302 Redirect vastauksen, joka ohjaa clientin varsinaisen tietosisällön sisältävään URL:ään. Selaimien ja useimpien client-frameworkien tapauksessa tämä tapahtuu automaattisesti.

Kun client noutaa lyhyen URL:n, se saa vastauksen :

pri:~$ telnet data.foli.fi 80
Trying 192.103.106.131...
Connected to siri.foli.fi.
Escape character is '^]'.
GET /gtfs/stops HTTP/1.0
Host: data.foli.fi

HTTP/1.1 302 Moved Temporarily
Server: nginx
Date: Sat, 23 May 2015 16:05:14 GMT
Content-Type: text/json;charset=utf-8
Connection: close
X-Powered-By: PHP/5.4.39-0+deb7u2
Location: http://data.foli.fi/gtfs/v0/20150523-123805/stops
X-Cache-Gate: EXPIRED

{
    "host": "data.foli.fi",
    "gtfspath": "\/gtfs\/v0",
    "datasets": [
        "20150523-123805"
    ],
    "latest": "20150523-123805",
    "go": "http:\/\/data.foli.fi\/gtfs\/v0\/20150523-123805\/stops"
}

Useimmat täysjärkiset client-frameworkit osaavat viimeistään päälle kytkettävän option myötä seurata vastausta automaattisesti (HTTP 302 & Location:-header). Mikäli kuitenkin client-framework ei osaa, tai jostain syystä ei voida käyttää (telnet-80) automaattista etenemistä, kannattaa huomioida, että vastauksessa on JSON-koodattuna mukana tarvittava tieto, mistä todellinen tietosisältö löytyy.

pri:~$ .... | php -r 'print_r(json_decode(file_get_contents("php://stdin")));'
stdClass 
(
    [host] => data.foli.fi
    [gtfspath] => /gtfs/v0
    [datasets] => Array
        (
            [0] => 20150523-123805
        )

    [latest] => 20150523-123805
    [go] => http://data.foli.fi/gtfs/v0/20150523-123805/stops
)

Varsinaiset data-linkit ovat siis dataset-kohtaisia

Best-practise, mikäli olennaista osoittaa yhtenäiseen? (coherent) datasisältöön.

Nouda saatavilla olevat datasetit

http://data.foli.fi/gtfs

{
    "host": "data.foli.fi",
    "gtfspath": "\/gtfs\/v0",
    "datasets": [
        "20150523-123805"
    ],
    "latest": "20150523-123805",
    "success": false,
    "subpaths": [
        "agency",
        "stops",
        "routes",
        "trips",
        "stop_times",
        "calendar",
        "calendar_dates",
        "shapes"
    ]
}

Osoita kyselyt tämän jälkeen samaan datasetiin

http://data.foli.fi/gtfs/v0/20150523-123805/agency
http://data.foli.fi/gtfs/v0/20150523-123805/stops