Trafiklab - metoddokumentation
Detaljinformationen för varje API har en flik som leder till dokumentation. Detta är förstås en av de viktigaste flikarna och i synnerhet är det dokumentationen för de tillgängliga metodandropen som är viktig.
Metoddokumentation
Hur dokumentationen ser ut skiljer sig lite ifrån API till API. I vissa fall kanske anropet inte kan ta några parametrar och det kanske alltid returnerar ungefär samma sak . I dessa fall är API-anropet i stort sett samma sak som om man skulle hämta den vanlig, statisk webbsida.
Avancerade metoder
För de mer avancerade anropen så fungerar dokumentationen så här. Först beskrivs utförligt vad anropet gör och vad det är avsett för (i vissa fall kan man klicka på anropet och komma till en sida med mer information). Det finns ofta information om var den bakomliggande data kommer ifrån. I vissa fall kanske data kommer ifrån olika källor och har sammanställts. Då kanske viss data kommer att skilja sig något ifrån övrig data. Här står även vad som händer om ett anrop misslyckas, så att du vet hur du ska hantera dessa fall.
REST URL
Därefter följer en beskrivning av hur URL:en ska se ut när man anropar API:et. Alla API:er som Trafiklab erbjuder är nästan uteslutande REST API:er. Följdaktligen kommunicerar din applikation med API:erna som normal webbtrafik. Alla anrop baseras på HTTPS och är följaktligen krypterade och relativt säkra. Kom ihåg att det trots detta är en god sed att validera inkommande data, så att den verkligen innehåller det som är tänkt!
API-nyckel
Anrops-URL:en innehåller alltid din API-nyckel. Detta är alltså den nyckel du erhållit när du registrerade ditt projekt. Se till att använda rätt nyckel för varje API och kom ihåg att det även kan röra sig om olika nycklar för olika projekt.
Tänk på att du bör skydda din nyckel! Om du lägger med anropet direkt i en webbsida, kommer användarna att kunna se din nyckel om de väljer att titta på koden för din sida. Generellt sett är det bäst om du har en serverdel som genomför alla API-anrop till externa tjänster och sedan skickar resultaten till din webbklient.
Svarsformat
För de flesta API-anrop anges även vilket format man vill att eventuell svarsdata ska vara i. Man kan oftast välja mellan JSON och XML.
Parametrar
I de flesta fall kan man även skicka med olika typer av parametrar för att mer precist styra vad det är man vill komma åt. Det finns en lång tabell som visar vilka parametrar som är tillgängliga. Vilken datatyp de förväntas ha. Huruvida de är obligatoriska eller ej. Varje tabellrad avslutas med en beskrivning över vad parametern är till för.
Resultat
Resultaten kan vara olika ifrån API till API. De mer avancerade följer denna mall.
Exempel
Under rubriken ”Resultat” visas ett exempel på hur svarsdata kan se ut ifrån API-anropet. Man visar hur resultatet kan bli att se ut i såväl JSON som XML.
Diagram
Ibland följer ett följer ett diagram som beskriver hur dataposterna är sammansatta.
Svarsdata
Sedan följer en tabell som beskriver vad varje variabel i en post är till för. Där anges vilket namn variabeln har, vilken datatyp den ska ha samt en beskrivning. Beskrivningen anger mer specifikt vad variabeln är till för samt hur de möjliga värdena ska tolkas.
I vissa fall kan t.ex. datatypen vara en sträng och då anger beskrivningen hur denna sträng ska tolkas. Ett exempel på detta kan vara en variabel som heter time, som rapporteras som en sträng. Denna sträng ska sedan tolkas enligt mallen HH:MM:SS. Det vill säga; timme, minut och sekund åtskilt av ”:”. Detta kan alltså innebära att din applikation måste tolka och omvandla vissa typer av data innan de kan börja användas.
Nästa aktivitet
Men för att kunna gå vidare måste vi registrera oss på sajten...