APIer

Idag lär vi oss om apier!
Vi utforskar API:er och hur man använder dessa för att kunna kommunicera med andra system. Lär dig hur du med lite kod kan skicka sms eller hämta information om tunnelbanan hos SL.

Vi jobbar i par, det går också bra att sitta tre personer tillsammans.
Ingen sitter ensam och vi hjälper varandra att leta, hitta, tolka och testa!

Hjälp de träna “frågemusklerna” (Be alla sträcka upp ena armen högt upp i luften. Allihop! och sedan andra också. Visa gärna själv samtidigt. … “sådär” - nu har alla tränat sina frågemuskler! Så om du har en fråga så sträck upp handen!

👩🏾‍💻 « indikerar en uppgift.
🐷 « när du ser grisen kan du klicka på den för att få mer detaljerade steg att följa.

1. Vad är ett api?

Vad handlar apier om?
Kanske vill du läsa om apier innan du ger dig i kast med att utforska och testa api:er.

2. Verktyg för att utforska apier

Mjukvaran POSTman är ett verktyg du kan använda för att lära dig om och utforska api:er.

👩🏾‍💻 Installera mjukvaran POSTman .

  1. Besök getpostman.com
  2. Under “Download the free Postman App:” klickar du på den knapp som matchar det operativsystem du har:
    ladda ner postman appen - knapparna på hemsidan getpostman.com
Om du använder linux anar jag att du redan är bekväm med hur du gör för att installera nya program. Om inte, snälla ta skärmdumpar medan du klurar ut detta och dela med dig till hej@kodkurs.se

Såhär kan filen du laddat ner se ut:
öppna zip-filen (packa upp)
Packa upp zip-filen.

Dra postman.app-filen till “applications-mappen” (Program).
öppna zip-filen (packa upp)

Dela gärna med dig av hur detta ser ut till hej@kodkurs.se!

👩🏾‍💻 Öppna appen POSTman

Ungefär så här ser det förmodligen ut för dig nu:

postman - när du först öppnar den

Klicka på “Take me straight to the app. I’ll create an account another time.”

postman - när du först öppnar den

Gör ett anrop till kodkurs.se.
Skriv http://kodkurs.se i rutan där det står
“Enter request URL”.
postman - första anropet

Tryck på den blå knappen (send)
postman - skicka

🐒 Vad hände?
Du “knackade på” hos kodkurs.se någonstans ute på internet, och fick ett svar tillbaka. kodkurs.se response Det svar du har fått är samma svar som din webbläsare får när du besöker kodkurs.se! När din webbläsare får svaret så tolkas svaret och en hemsida visas för dig.

Öppna en webbläsare och besök http://kodkurs.se

Högerklicka och välj “visa källa”, “view source”, eller “visa sidans källkod”…

Ser du att det är samma sak där som du fick som svar i POSTman? Samma sak gäller api:er, de finns på en adress någonstans ute på nätet, och du behöver känna till adressen (URL) för att kunna prata med apiet, svaren kommer se lite annorlunda ut.

Det anrop du precis har gjort kallas på engelska för request (engelska för förfrågan). Du har gjort en förfrågan på adressen http://kodkurs.se och fått ett svar.

Statuskoder

När du gjorde ett anrop till kodkurs.se och fick ett svar så fick du också lite mer information om svaret. Du fick med en statuskod. status code in postman


200 innebär “aaaallt väääl”.

🐒 När kan jag få något annat än 200?
Låt mig besvara den frågan med en ny uppgift!

Gör ett anrop till http://kodkurs.se/sidan-finns-inte
anrop till kodkurs.se/sidan-finns-inte

Svaret är ju alltså detsamma som du får om du besöker http://kodkurs.se/sidan-finns-inte i din webbläsare.
kodkurs 404

Ser du att du fått en annan statuskod? status code 404

Aha! Så allt är inte väl. Du har ju alltså fått ett svar, en hemsida, precis som förut, men statuskoden 404 säger dig att det som du frågade efter inte gick att hitta. Kanske hittar du ledtrådar eller hjälpsamma kommentarer i svaret, men det är statuskoden som säger dig att du kanske har fel adress, eller att du frågar efter något som helt enkelt inte finns!

Besök http cats (😺 😸 😹) och kolla på några olika statuskoder.


Det finns många statuskoder, viktigast att känna till är grupperingarna:
100 - informativa statuskoder
200 - ok (success)
300 - omdirigering (redirect)
400 - du har gjort något fel (client error)
500 - servern gör något fel (den dator du försöker pratar med misslyckas)

Läs gärna mer om statuskoder på wikipedia.

Vi utforskar och lär oss använda ett riktigt api.

Nu använder vi postman för att prata med 46elks-apiet.
46elks kan du använda för att skicka sms. Kanske har du fått en påminnelse inför ett viktigt inbokat möte tidigare? Eller en bekräftelse på en bokning via sms? Att automatisera sådana utskicka kan du göra genom att använda ett api. Då kan du själv skriva kod som automatiskt säger till apiet att skicka ett sms åt dig.

Först behöver vi klura ut adressen till apiet.
Alltså letar vi efter dokumentationen till api:et efter en adress (URL).

Hitta till dokumentationen för 46elks-apiet.

Vi börjar med att gå in på hemsidan 46elks.com

Vi letar efter “Documentation”, “Docs” eller “API reference”. Det är vanliga benämningar på dokumentationen för api:er.

I huvudmenyn hittar vi “docs” och klickar där.

Gör ett anrop till 46elksapiet.

Skriv in adressen till 46elks-apiet (https://api.46elks.com/a1/)
api request to 46elks api
Tryck på send

Du fick förmodligen ett svar tillbaka i stil med detta:
API access require proper Basic HTTP authentication.
Read documentation or examples.

Svaret: Autentisiering krävs
det tillsammans med statuskoden 401, säger dig att du måste autentisera dig för att få använda tjänsten. Aha! Vi behöver en nyckel in till denna dörr.

När du behöver autentisera dig skapar du vanligtvis först ett konto hos tjänsten, och sedan får du ofta antingen ett användarnamn och ett lösenord att autentisiera dig med, eller en sträng med olika bokstäver och andra tecken som räcker istället för användarnamn och lösenord.

I introduktionen i dokumentationen för api:et står det:
Basic http authentication is used for access control and you can find your API credidentials in the dashboard.
Det säger oss att vi kommer behöva ett användaramn och ett lösenord.

Vad är Basic auth?
Det handlar om att du skickar med ett användarnamn och ett lösenord när du gör en förfrågan.

Skaffa dig ett konto hos 46elks.
Du behöver ha tillgång till din telefon, eftersom du blir uppringd automatiskt för att bekräfta att du är du, och inte en bot!

Plocka fram ditt api-användarnamn ( username ) och api-lösenord ( password ) .
Obs! Tänk på att vara väldigt varsam med användarnamn och lösenord i publika sammanhang. Om du sitter på biblioteket eller befinner dig någonstans där någon kan se vad du gör, så kan det vara värt att du helt enkelt väntar lite med uppgiften. Om någon annan får tag på ditt användarnamn och lösenord till en tjänst, så kan de nyttja den tjänsten i ditt namn.
Hantera användarnamn och lösenord varsamt.
användarnamn och lösenordet som inloggad på dashboarden hos 46elks

🔑
Api-användarnamn & api-lösenord kan ibland kallas för “apinycklar” (eng. api keys).

Nu ska vi skicka med användarnamnet och lösenordet i postman. Gör ett anrop till 46elksapiet där du skickar med användarnamn och lösenord (basic auth).
Under Authorization ändrar du ifrån no auth postman authorization
till basic auth
postman basic auth
och sedan fyller du i ditt användarnamn och lösenord
postman basic auth username and password
tryck på send

username and password success

Vi är inne!


Testa att lägga till /me i slutet av adressen!

Gör en förfrågan till:
https://api.46elks.com/a1/me
👻 Vad fick du för svar?


endpoint/resource - ändelser så som /me kallas för endpoint eller resource.
(Ibland kallas hela https://api.46elks.com/a1/me för endpoint)
Det handlar alltså om vilken dörr hos api.46elks.com du knackar på. Du kan givetvis fråga efter olika saker bakom olika dörrar (endpoints), och genom att anropa olika delar av ett api, kan du få olika saker att hända. Låt oss få saker att hända!

Nu vill vi skicka ett sms.
Vi återvänder till dokumentationen och kollar vad det står där om hur en gör för att skicka ett sms .

Läs i dokumentationen hur en gör för att skicka sms.

Vi tolkar instruktionerna tillsammans.
“simply POST to the /SMS”
Hittills har vi gjort “GET” anrop, d.v.s. vi har frågat efter ett svar. Nu vill vi skicka information in till API:et, vi vill ju berätta vem sms:et ska skickas till och vad det ska stå i meddelandet. Det behöver vi ju skicka med.
Vi behöver alltså göra ett POST-anrop istället för GET-anrop.
Vad är skillnaden mellan GET & POST? Finns det fler?
Läs gärna mer om olika HTTP-anrop.

“The “from” number can either be one of your previously allocated mobile phone numbers or an arbitrary alphanumeric string.”
from handlar om vem sms:et ska anses komma ifrån. Du kan använda ditt egna telefonnummer. arbitrary alphanumeric string innebär att du kan sätta ihop en sträng med bokstäver och siffror som du använder som avsändare istället. Du kanske har fått sms ifrån t.ex. “PostNord” - det är en alphanumric string. Då kommer smset inte ifrån ett telefonnummer. Du kan alltså skicka sms ifrån t.ex. PINK. (Hur häftigt är inte det?! :D )

POST https://api.46elks.com/a1/SMS Det är alltså den kompletta adressen som vi ska göra anropet till, och vi ser att /SMS har lagts till i slutet. Denna adress gör vi anropet till.

Tabellen ( to, from, message ) visar vad vi kan skicka med för information.
Vem meddelandet ska skickas till. (to)
Vem det ska se ut som att meddelandet har skickats ifrån (from)
Innehållet i meddelandet (message)

Sedan är det detaljer kring vad och vem du kan ange som avsändare…


Skicka ett sms till dig själv!

1) Ändra anropet ifrån ett GET-anrop till POST-anrop.
postman change from GET to POST

2) Ändra adressen till rätt endpoint (https://api.46elks.com/a1/SMS)
3) Klicka på body
click body in postman
4) Ändra formatet till x-www-form-urlencoded (form-data brukar vara förifyllt)
Att vi ska använda x-www-form-urlencoded fick vi veta i introduktionen till api:et, i dokumentationen.
click body in postman


5) Fyll i key & value enligt instruktionerna i dokumentationen för att skicka med data så som vem det ska skickas till, varifrån och vad det ska stå i meddelandet.

Det som i dokumentationen ser ut ungefär såhär:
key-value-pair-in-docs
Skickar vi alltså med genom att skicka med det som innehåll (body) i vårt anrop:
key-value-pair-in-postman

Nu ser det ungefär ut såhär för dig:
postman sms with 46elks
6) Klicka på send.

Du har kommunicerat med ett api på riktigt!
Coola bananer! 🍌🍌🍌



🔥
Nu har vi värmt upp. När du känner dig redo fortsätter vi utforska Trafiklab!
Här finns apier där du kan hämta data ifrån kollektivtrafiken 🚂 🚃 🚍, i realtid!

PS Om du är intresserad av att bidra till att kollektivtrafiken utvecklas så är
🚂 Trainhack något för dig!

Trafiklab

https://www.trafiklab.se/

Låt oss testa att hämta ut data om kollektivtrafiken!
Detta material är inte helt slipat - om det är något som är oklart skicka gärna frågor till Trafiklab, eller fråga i olika forum, och om du inte finner hjälp någon annanstans, maila till hej@kodkurs.se!

  1. Skaffa dig ett konto hos trafiklab
  2. Kolla din e-post: En länk skickas till dig, som du måste klicka på för att kunna använda api:et
  3. Hos Trafiklabb är det apinyckel, istället för användarnamn och lösenord som gäller. Du kan läsa mer här: https://www.trafiklab.se/api/dokumentation/nycklar om hur det fungerar.
  4. Skapa upp ett nytt projekt: https://www.trafiklab.se/node/add/project.
    ResRobot - Reseplanerare och ResRobot - Stolptidtabeller 2 och SL Hållplatser och Linjer 2

    Obs!
    Tänk på att om den klagar, att du får felmeddelanden tillbaka, kolla då att du använder rätt nyckel! Varje tjänst har sin egen nyckel!
    Du hittar alltid tillbaka till dina nycklar här https://www.trafiklab.se/user/keys .

  5. Klicka på API-nycklar -> Hämta nyckel https://www.trafiklab.se/api/dokumentation/nycklar</span>

  6. För att komma vidare behöver du godkänna ett längre avtal som handlar om att du inte kommer missbruka tjänsten. Välj för övningens skull [Jag godkänner].
  7. Nu ser du en API-nyckel framför dig
  8. Nu letar vi efter dokumentationen på denna sida: https://www.trafiklab.se/api/sl-hallplatser-och-linjer-2 . Vi ser detta exempel:
    http://api.sl.se/api2/LineData.json?model=line&key=###dinnyckelhär###
    Då får vi ett svar som ser ut såhär:
    { "StatusCode": 0, "Message": null, "ExecutionTime": 417, "ResponseData": { "Version": "2017-05-05 00:05", "Type": "Line", "Result": [ { "LineNumber": "1", "LineDesignation": "1", "DefaultTransportMode": "blåbuss", "DefaultTransportModeCode": "BUS", "LastModifiedUtcDateTime": "2007-08-24 00:00:00.000", "ExistsFromDate": "2007-08-24 00:00:00.000" }, { "LineNumber": "1", "LineDesignation": "1", "DefaultTransportMode": "Waxholmsbolagets", "DefaultTransportModeCode": "SHIP", "LastModifiedUtcDateTime": "2009-09-02 00:00:00.000", "ExistsFromDate": "2009-09-02 00:00:00.000" }, { "LineNumber": "10", "LineDesignation": "10", "DefaultTransportMode": "tunnelbanans blå linje", "DefaultTransportModeCode": "METRO", "LastModifiedUtcDateTime": "2007-08-24 00:00:00.000", "ExistsFromDate": "2007-08-24 00:00:00.000" }, { "LineNumber": "101", "LineDesignation": "101", "DefaultTransportMode": "", "DefaultTransportModeCode": "BUS", "LastModifiedUtcDateTime": "2012-08-24 00:00:00.000", "ExistsFromDate": "2012-08-24 00:00:00.000" }, { "LineNumber": "102", "LineDesignation": "102", "DefaultTransportMode": "", "DefaultTransportModeCode": "BUS", "LastModifiedUtcDateTime": "2012-08-24 00:00:00.000", "ExistsFromDate": "2012-08-24 00:00:00.000" }, { "LineNumber": "103", "LineDesignation": "103", "DefaultTransportMode": "", "DefaultTransportModeCode": "BUS", "LastModifiedUtcDateTime": "2016-03-05 00:00:00.000", "ExistsFromDate": "2016-03-05 00:00:00.000" }, { "LineNumber": "11", "LineDesignation": "11", "DefaultTransportMode": "tunnelbanans blå linje", "DefaultTransportModeCode": "METRO", "LastModifiedUtcDateTime": "2007-08-24 00:00:00.000", "ExistsFromDate": "2007-08-24 00:00:00.000" }, { "LineNumber": "11", "LineDesignation": "11", "DefaultTransportMode": "Waxholmsbolagets", "DefaultTransportModeCode": "SHIP", "LastModifiedUtcDateTime": "2009-09-02 00:00:00.000", "ExistsFromDate": "2009-09-02 00:00:00.000" }, { "LineNumber": "110", "LineDesignation": "110", "DefaultTransportMode": "", "DefaultTransportModeCode": "BUS", "LastModifiedUtcDateTime": "2007-08-24 00:00:00.000", "ExistsFromDate": "2007-08-24 00:00:00.000" }, { "LineNumber": "112", "LineDesignation": "112", "DefaultTransportMode": "", "DefaultTransportModeCode": "BUS", "LastModifiedUtcDateTime": "2007-08-24 00:00:00.000", "ExistsFromDate": "2007-08-24 00:00:00.000" }, { "LineNumber": "113", "LineDesignation": "113", ....

    Tada! Du har nu hämtat ut information om vilka linjer som finns!

  9. Låt oss titta på stolptidtabeller!
    https://www.trafiklab.se/api/resrobot-stolptidtabeller-2

    Dokumentationen finns alltså här:
    https://www.trafiklab.se/api/resrobot-stolptidtabeller-2/resrobot-stolptidtabeller-2 .
    och här:
    https://www.trafiklab.se/api/resrobot-stolptidtabeller-2/resrobot-stolptidtabeller-2-avgaende-trafik

    Vi testar! https://api.resrobot.se/v2/departureBoard?key=&id=1&maxJourneys=10

    Aha, vi behöver ett ID som motsvarar hållplatsen, då får vi leta upp det!

    Vi läser på här:
    https://www.trafiklab.se/api/resrobot-reseplanerare/resrobot-reseplanerare-platsuppslag Och så testar vi https://api.resrobot.se/v2/location.name?key=<din nyckel="">&input=Alvik</din>

    Svaret ser ut ungefär så här:
    Här kanske du vill visa hur de gör för att få svar som json!
    Aha! wow det finns flera hållplatser som innehåller namnet Alvik!

    Vi testar att använda detta id: 740020755 (Alvik T-bana) för att se ifall vi kan få fram avgångar därifrån!
    Gör ett anrop till:
    https://api.resrobot.se/v2/departureBoard?key=<din nyckel="">&id=7400207551&maxJourneys=10</din>

    För dig kommer det alltså se ut ungefär såhär:

    https://api.resrobot.se/v2/departureBoard?key=ce398a424-adse-dj29-b7c7-10f2aa1r342&id=740020755

    TADA! Nu visar du de kommande avgångarna ifrån Alviks T-banestation!

    Heja dig!

Repetition

Kan du förklara dessa ord för andra? Om det finns något ord som du undrar över - fråga ifall det är någon annan som förstår vad de betyder.

  • baseurl
  • GET-anrop
  • POST request
  • docs
  • basic auth
  • key value pair

Bonus! En utmaning!
Vågar du försöka ta reda på vad RESTful api innebär?

Fler apier!

Återsamling

Återsamling, och tid för att ställa frågor och att få ta del av frågor och svar som andra utvecklat.

Några frågor?



Vad har du lärt dig?

Vad har du lärt dig om apier?
Vad kan du förklara för någon annan?
Vilka nya ord och förkortningar förstår du nu?
Kika på APIer - vad kan jag?



in English

Vem ligger bakom denna kurs?

Victoria Wagman som har arbetat som lärare i webbutveckling, och idag arbetar som programmerare hos 46elks.

Detta material byggs upp lite i taget.