Några undringar och synpunkter efter första test av SL Transport
Några undringar och synpunkter efter en första titt och användning av SL Transport + dokumentation. Jag har provat "Departures from site".
Det har kanske smugit sig in något missförstånd här eller där, men detta var första intrycket:
Lite allmänna observationer:
Det har kanske smugit sig in något missförstånd här eller där, men detta var första intrycket:
- Frasen ”a maximum of 3 departures for each line & direction” är svår att få att gå ihop med ”forecast: Defines the window of time, in minutes, for which to fetch upcoming departures and deviations starting from now. A value of 30 means departures and deviations for the next 30 minutes will be included.” – vilken är det som gäller egentligen? Max tre, eller alla avgångar fram till forecast? Det är ganska svårt att förstå ”forecast” så länge det samtidigt står att jag får max tre per linje och riktning. En måste vara fel, och av allt att döma är det "forecast" då jag aldrig sett samma linje+destination upprepas mer än tre gånger.
- Angående ovanstående punkt (jag talar till de som designat API:et): Det framstår spontant som ganska begränsande för någon som försöker planera sin resa om de endast får se de tre närmsta avgångarna inom 20 minuter, eller vad de slumpmässiga extremfallen nu kan tänkas vara. Det känns också vanskligt som utvecklare när ni gör på detta sätt: Jag har länge haft en kronologisk presentationsmodell (”tidslinje”) av avgångar, där användare ska kunna känna sig helt trygga med att de kan se *alla* avgångar inom ett visst intervall, men ni dikterar nu att en sådan mental modell inte är tillåten, vare sig för utvecklare eller användare… Om jag försöker mig på detta ändå så verkar det vara er avsikt att garantera att min tidslinje ska bli full med ”hål” där det egentligen borde finnas en avgång, men som jag inte får veta något om. För att ändå garantera att visa alla avgångar tvingas jag därför kapa listan med avgångar direk efter det första linje-destinationsparet som har upprepats tre gånger (vilket teoretiskt sett kan ske efter totalt tre avgångar…). Jag kan bara undra: Om ni föreskriver hur datan ska presenteras och därmed homogeniserar presentationen av den, vad är då tjusningen med öppen data? Om vi alla behöver presentera den likadant, tillsynes utan anledning, ja, då räcker det ju med en eller ett par implementationer – jag blir ändå hindrad från att försöka designa något utstickande. Den mentala modell för presentation som ni valt åt mig och som jag nu måste använda tilltalar mig inte. Jag vill presentera datan annorlunda än vissa andra klienter, dvs. erbjuda en alternativ modell, men det går inte längre, som jag tolkar det. API:et känns därför inte som en ordentlig ersättare, och då har vi inte ens gått in på att ni givit mig mindre än en månad att arbeta om hela den presentationsmodell som ni nu gjort ogångbar, även om jag hade varit beredd att göra det.
- StopDeviation och DepartureDeviation är olika. Varför säger SiteDeparturesResponse att dess stop_deviations ska innehålla ”stop deviations” men har en lista av DepartureDeviation som typ? Är namnet eller typen fel? Exempeldata pekar på att typen är rätt. Är då namnet och beskrivningen fel?
- Departure.deviations är angivet som typen string, men jag servas en tom lista.
- Alla SiteId jag söker fram med https://journeyplanner.integration.sl.se/v1/typeahead.json ger tomma resultat, men det ges samtidigt ingen indikation på att något är fel (?) utan levererar en tillsynes giltig datastruktur. Parametern SiteId har som beskrivning ”Can be obtained from […] the SL stop lookup api” dvs. nyss nämnda URL som jag blev ombedd att byta till innan 15:e mars. Detta stämmer uppenbarligen inte, utan jag tvingas skala av de fyra första tecknen för att få ett giltigt SiteId (Eller de fem första? Eller extrahera FGEDCBA i 3FG1EDCBA..?), ens för användning i Realtid4, vilket mejlet inte gav någon förvarning om.
- Exemplet för ”group_of_lines” är felaktigt: ”example: tunnelbanans gröna linje”. Alla dessa börjar med versal (”T”) för tunnelbanan. En liten ändring som likväl kan orsaka en krasch om man väljer att lita på dokumentationen och exemplen.
- DepartureJourney har ett id som är av typ number, men dess min, max och exempel ger intryck av att det är typen integer. De flesta andra id ser ut att vara integer. Ska jag förbereda mig på decimaler?
Lite allmänna observationer:
- Det framgår inte på sidan vad röd asterisk innebär i svarsdatan.
- Det framgår inte huruvida eventuellt uteblivna fält kommer att sakna nyckel helt eller ha värdet null (eller blir en tom lista).
- Det är oklart ifall API:et förbehåller rätten att utöka sina Enum i framtiden, vilket i så fall skulle kräva att de representeras mer förlåtande på klientsidan.
- Det framgår inte vilken tidszon common.localDatetime ska tolkas som. Man måste då gissa att det inte är UTC utan ”Europe/Stockholm” (som förut). ”Local” förlorar något av sin slagkraft när allt presenteras på engelska.
- Det vore bra om inte 40% av sidan för dokumentationen togs upp av en statisk sidomeny i 1080p i porträttläge. Hela dokumentationen får inte plats horisontellt, och man tvingas minska storleken, eller använda uBlocks Element Zapper på menyn och öka max-width på page-div:en. Jag borde inte behöva installera tillägg och redigera HTML eller hämta en 1200x1920-skärm för att få plats med dokumentation i porträttläge.
- Att det krävs Content-Type application/json gör det eventuellt lite mindre välkomnande eftersom jag då i t.ex. Safari behöver skapa en lokal förbigång (Webbgranskare > Källor) för sidhuvudet för att testa en anrops-URL lite snabbt. Kanske mindre kul för dem som gör sitt första API-anrop.
Följ inlägget
2
följare
Tack för den utförliga återkopplingen.
1. Det är nog "vilken som kommer först", så "högst 3 avgånger för varje linje + destination, inom fönstret som specificeras av forecast." Däremot lyckas jag inte utöka fönstret genom att speca högre värden för forecast. Vi förtydligar dokumentationen samt felanmälar forecast-parametern till SL.
2. Jag håller med i att de nya begränsningar inte går ihop med en del användningsfall. Du har helt rätt att målet är att man ska kunna bygga vilka lösningar som helst, och där har vi SLs GTFS-RT data som ett alternativ, dock krävs det en del mer utveckling. Jag kollar om SL kan utöka hur många avgånger som visas så att man inte lika snabbt blir tvungen att ta sig till de mer komplicerade GTFS data.
3. Detta rättar vi i dokumentationen.
4. Detta rättar vi i dokumentationen.
5. Detta är ett problem som introducerades när SL ville se till att reseplaneraren och typeahead ger samma resultat, men här använder de sig av andra id:ar än i reseplaneraren. Jag felanmälar detta, då den där typeahead returnerar inkorrekta svar. Anledningen till att mejlet inte varnade om det är att förändringen skedde i efterhand (och även var oväntad för oss).
6. Vi rättar detta i dokumentationen.
7. JourneyId är ett integer och kommer inte innehålla decimaler. Vi förtydligar att detta är ett heltal, men större än en int brukar vara.
8. Detta är nog någon "required" annotering och hur SwaggerUI visualiserar detta. Det kan dock vara missvisande, då fält alltid ska vara med, och verkar resultatet av tolkning mellan olika specifikationsformat. Här behöver vi nog gräva lite mer innan vi kan rätta det.
9. Utifrån det jag ser skulle jag utgå ifrån att det blir tomma listor, och det här hänger lite ihop med punkt 8. Vi kollar om det går att verifiera och förtydliga.
10. Enums som JourneyStateEnum borde inte få nya värden utan förvarning, och jag är 99% säkert på att de aldrig kommer få nya värden då de är baserad på befintliga standarder för kollektivtrafikdata. Inte alla värden kommer användas i verkligheten. Sen tycker jag att det alltid är bra att ha en fallback till en neutral standardvärde, tex till "EXPECTED", om det inte går att läsa en värde.
11. Vi lägger till denna information, det är Europe/Stockholm.
12. Vi tar med detta när vi ser över layouten av dokumentationssidor, där vi redan har en del andra synpunkter som också måste åtgärdas. 1080p-bredd har inte varit med i tester tidigare, men är ändå en rimligt med tanke på att man kan vrida ett skärm till porträttläge.
13. Detta har redan felanmälts då Content-Type inte ska skickas på GET anrop, sen har vi även förespråkit att anta application/json när inget har specificerats för att underlätta anrop.
13b. Den här nämndes inte men kan vara av interesse, även för andra som läser denna tråd: CORS headers saknas vilket gör det svårt att använda API:et direkt från javascript i en webbläsare samt hindrar att testa API:et direkt från dokumentationen. Detta har redan felanmälts och kommer lösas.
Hoppas detta besvarar dina frågor.
Hälsningar,
Bert
Angående begränsningen på 3 avgångar per linjeriktning så har SL satt den på ett värde som balanserar flera resultat med en begränsad last på back-enden, och vill de helst behålla det befintliga värdet. De är dock öppet för att höra om ditt användningsfall, så om du vill går det att få kontakt med deras teknisk ansvarig person för API:et direkt.
GTFS filer är stora, och går typiskt inte att hantera på mobila apparat. Det går dock fint att hantera även på små servrar eller raspberry pis för den delen, särskilt när man filtrerar bort trafik så att man bara behåller de dagar man är intresserade i. Själva undersöker vi också möjligheterna att förbättra på tex Resrobot stolptidtabeller med hjälp av all GTFS data som vi har tillgängliggjort de senaste åren, men tyvärr finns det inga konkreta planer för detta än.
Angående JSON så ska alla nycklar vara med, vi behöver undersöka lite själv vad SL exakt syftar på med stjärnorna, kan vara att de aldrig ska vara null men det måste som sagt undersökas.
Hälsningar,
Bert