Policies and recommendations
Traffic data is provided through REST-style interface. To maximize caching, single specific url contains single specific JSON dataset common to all requestor.
- All data fetched is cached and proxied on front side server. Clients cannot bypass the front side proxy or have direct contact with backend system. Caching times of cource vary. For example SIRI-VM messages have 2 second TTL while GTFS-replies practically never expires.
- Clients cannot parametrize their queries or direct frontend server to return sorted, filtered or otherwise unique single client specific results. For every single url the interface returns same dataset for every requestor. The principle is that data is supposed to be filttered on client itself, not on server providing them.
- Returned content is not sorted unless URL's documentation states that it's sorted, for example alphabetically. Please take note that EVEN if data currently looks like it's ordered by some factor, it's not a promise unless documentation states it as promise. For scalability filtering and sorting is most efficient to do at client device itself unless need for specific ordering is probably same for every querier.
Client must support gzip-encoding on HTTP level.
- Despite what is actually requested, frontend server always acts like HTTP-request constains Accept-Encoding header with value "gzip". Depending of the size of the reply, it might be returned as compressed or not, even despite what you asked. (Of course if it's compressed, it contains appropriate Content-Encoding response header).
- This harsh requirement is for reducing the bandwidth consumption and easing the content generation. Especially SIRI-VM urls contains large, rapidly changing, very short living datasets. Producing them both as compressed and uncompressed would cause excessive burden to frontend system.
- In practice browsers, handhelds and most of common client frameworks (Java, JS, PHP, curl, node.js, etc.) handle gzipped content automatically so this requirement should not need to be addressed in any way in your client software.
If possible, clients should use differentiating User-Agent headers.
- If possible, User-agent -header should display application name, platform, maybe contact and link to possible information page. For example :
MyApp/1.0.1; (Android/*; +http://mysite.fi/MyApp; firstname.lastname@example.org)
- Collected log data is mainly used for internal usage tracking and reporting. In case you want keep your application private and for example don't want it to be published on some listing, please include text no-public into the user agent line. For example :
MyTestApp/1.0.1; (Android/*; +http://mysite.fi/MyApp; email@example.com; no-public)
- WWW-browsers are naturally excluded from User-agent requirements.
Limits regarding the query rate :
- Current limit is max 32 requests per second with 64 request burst originating from single IP address. All responses are cacheable and especially long TTL resposes like GTFS-responses should be (allowed to be) cached locally.
- Server sends proper Cache-Control and Expires headers automatically. Browsers honor these headers, but mobile applications probably need additional code to support caching. For example in case of Android devices : (HttpURLConnection / HttpResponseCache)
- Because of Cache-Control and Expires headers there is also possibility to use your own dedicated simple www-cache in front of this frontend server and direct your clients to use that your server instead.
Interfaces supports only HTTP-GET -requests.
- Server sends Access-Control-Allow-Origin: *, but does not respond to OPTIONS -preflight requests.
Interface is available both as SSL and non-SSL.
- Anyway, to support faster handshaking and reducing load on serving side, non-SSL connections are strongly preferred.