Streaming

Strömmat data


API:et kan pusha förändrat data till klienter.

Förändrat data kan konsumeras i en dataström, så fort nytt data finns tillgängligt skickas det i realtid till ansluten klient. Tekniken som används är Server-Sent Events (SSE) som är en standard som beskriver hur servrar kan initiera dataöverföring mot klient när en klientanslutning har upprättats.

SSE skickas över vanlig HTTP och har inbyggd funktionalitet för t.ex. automatisk återanslutning och meddelande-ID:n. Javascript API:et EventSource är en HTML5-standard vilket innebär inbyggt stöd i webbläsare(*) för direktanslutning från webbläsare till API:et. Det finns också många implementationer av EventSource för olika språk och plattformar som PHP, .NET, Java m.fl.
(*) För webbläsare som saknar stöd för EventSource kan s.k. polyfill användas.

Genom att i frågan på QUERY-elementet sätta attributet sseurl="true" så kommer en dynamisk endpoint (URL att ansluta till) för just denna fråga att skapas. URL:en bifogas svaret i INFO.SSEURL.

Ex:

<REQUEST>
    <LOGIN authenticationkey="yourauthenticationkey" />
    <QUERY sseurl="true" objecttype="TrainAnnouncement" orderby="AdvertisedTimeAtLocation" schemaversion="1.3">
        <FILTER>
            <AND>
                <EQ name="AdvertisedTrainIdent" value="129" />
                <GTE name="ScheduledDepartureDateTime" value="2019-05-07T00:00:00.000+02:00" />
                <LT name="ScheduledDepartureDateTime" value="2019-05-08T00:00:00.000+02:00" />
                <EXISTS name="TimeAtLocation" value="true" />
            </AND>
        </FILTER>
        <INCLUDE>LocationSignature</INCLUDE>
        <INCLUDE>ActivityType</INCLUDE>
        <INCLUDE>AdvertisedTimeAtLocation</INCLUDE>
        <INCLUDE>TimeAtLocation</INCLUDE>
        <INCLUDE>ScheduledDepartureDateTime</INCLUDE>
    </QUERY>
</REQUEST>
{
    "RESPONSE": {
        "RESULT": [
            {
                "TrainAnnouncement": [],
                "INFO": {
                    "SSEURL": "https://api.trafikinfo.trafikverket.se/v2/data.json?ssereqid=ee9de85f-1789-4990-929e-64bae7aaa6da"
                }
            }
        ]
     }
}

Den skapade endpointen innehåller nu en dataström med allt data som förändrats efter datat som mottogs i svaret.

Varje meddelande som klienten mottager innehåller ett eller flera objekt samt också ett id som identifierar position i dataströmmen. Om anslutningen mot API:et avbryts på grund av kommunikationsstörningar på internet kommer klienten själv att automatiskt försöka återansluta. När anslutningen återupprättats kommer dataströmmen innehålla de förändringar som eventuellt har skett men som klienten ännu inte mottagit. Det är också möjligt att manuellt återansluta till en dynamisk endpoint utan att så att säga börja från början i dataströmmen. Det görs genom att bifoga senast mottagna id:t som parameter lasteventid till URLn i anropet, exempelvis: https://api.trafikinfo.trafikverket.se/v2/data.json?ssereqid=161224a2-fa09-4f13-a5c7-fabde93658bc&lasteventid=6686784370679742465

Alternativt kan förstås istället en ny fråga med uppdaterat filter ställas mot API:et varpå en ny SSEURL genereras.

En dynamisk endpoint som inte används städas vid behov bort. Det innebär att en klient aldrig bör förlita sig på att en endpoint garanterat existerar. Om en anslutning inte kan göras ska klienten skapa en ny endpoint att ansluta till.

För att bevaka en kollektion och även prenumerera på borttag av objekt måste frågans QUERY-element innehålla attributet includedeletedobjects="true". Om limit varit definierad i frågan kommer maximalt antal objekt per meddelande i dataströmmen att begränsas till motsvarande värde. Om limit="0" blir initialt svar tomt och värdet ignoreras i dataströmmen (max antal objekt per meddelande är då 1000).

Det id som mottages i SSE-meddelandet är samma id som LastChangedId som används vid manuell hämtning av förändrat data.

API-portalen innehåller tre stycken exempel för streaming (Exempelkod).

  • Ett enkelt exempel (EventSourceDemoClient_Simple.htm) som enbart visar anslutning med EventSource.
  • En lite mer avancerad testbänk (EventSourceDemoClient.htm) där frågor kan ställas och SSE-anslutningar göras.
  • En .NET-applikation som lyssnar på tågannonseringar för ett angivet tågnummer.

SSE Specification: https://html.spec.whatwg.org/multipage/server-sent-events.html
SSE Documentation: https://developer.mozilla.org/en-US/docs/Web/API/EventSource
Polyfills: https://polyfill.io/v2/docs/features/
Polyfill EventSource CDN: https://cdn.polyfill.io/v2/polyfill.js?features=EventSource
SSE klientimplementationer NuGet: https://www.nuget.org/packages?q=sse