En introduktion till REST

Behovet av API:er har blivit allt viktigare då fler och fler arkitekturer bygger på multi- eller omnikanal lösningar där omsättning av informationskällor är mycket högre än tidigare. För att detta ska fungera så behöver informationen vara lättillgänglig via API:er som är enkla att integrera mot. API-hanteringen bör således vara en central del en modern verksamhets strategiska fokus.

Introduktion

Grovt förenklat är ett API ett gränssnitt som applikationer använder för att utbyta information med varandra. När man idag pratar om ett API avses vanligen mer specifikt ett publikt åtkomligt webbaserat API som returnerar JSON eller XML objekt. API:et är inte en databas, och inte heller en server, utan det är koden/applikationen som hanterar accesspunkten för den specifika informationen som system behöver kunna tillhandahålla för externa system.

API:er ger oss möjligheten att:

• Från vald källa med specificerade urvalsparametrar hämta den information vi är intresserad av
• I vald källa uppdatera med ny eller förändrad information

API:er utvecklades initialt kring ett fjärrproceduranrop, ett sk. RPC anrop. Trots att funktionaliteten lyftes till API:er så medförde detta att API:erna såg ut som om det var lokal exekvering av den kod man skulle nyttja. Detta innebar att det var svårt att överföra dessa API:er till webben samt att göra dem användarvänliga. Protokoll som SOAP, försöker lösa problem som ovan, men tvingar ofta på utvecklaren strikta ramverk, som kan vara svåra att hantera.

Användandet av enklare alternativ som REST (Representational State Transfer) har vuxit exponentiellt eftersom det ger många fördelar.

I Utvecklarportalens REST API profil och i avsnitten om REST-API:er i playbook kommer vi enbart fokusera på webbaserade API:er som via en så kallad endpoint kan returnera svar på anrop från en klient.

Varför behöver man API:er?

Tänk dig följande scenario: du vill i din applikation tillhandahålla väderinformation via SMHI:s vädertjänster. Du skulle då kunna ladda ner aktuell prognos och lägga upp denna i din applikation, alternativt lagra informationen i en databas och låta din applikation läsa informationen från databasen. Ett sådant arbetssätt innebär att informationen snabbt blir inaktuell och det blir svårt och arbetsintensivt att hålla informationen aktuell. Ett bättre sätt är därför vara att använda ett API som SMHI tillhandahåller för direkt tillgång till aktuell väderprognos. Applikationen håller sig med hjälp av API:et uppdaterad med aktuell information från källan. Detta arbetssätt minimerar administration och underhåll för applikationen och säkrar att korrekt information alltid kan presenteras.

API:er möjliggör integration där program, system och applikationer på ett enkelt sätt kan prata med varandra, en slags tolk som kommunikationen går igenom. API:er brukar också beskrivas som ett strukturerat sätt att överföra data från ett ställe till ett annat.

Vem kan skapa och tillhandahålla API:er?

I stora teknologiföretag är det idag en del av deras affärsverksamhet att tillhandahålla en del av informationen de har i sina system publikt, både genom webbplatser men även genom API:er. API:er tillhandahålls och underhålls även av till exempel myndigheter, organisationer, start-ups och enskilda individer som har information eller tjänster de vill kunna dela publikt. Informationen kan vara allt från allt från social media, rankingsystem, kartinformation, sångtexter, recept eller väderinformation. Förenklat kan man säga att vilken person eller organisation som helst som samlar information i sina system kan ha ett intresse av att göra denna information tillgänglig publikt.

Vad skiljer ett API från vanliga applikationer med en databackend kopplad mot en databas?

Ett API skiljer sig från vanliga applikationer genom att den inte behöver ha en “front end“, det vill säga ett GUI (Graphical User Interface), för att jobba med informationen i systemet. API anrop för att skriva eller läsa information kan ske direkt maskin till maskin.

Att skriva ett API

För att kunna skriva ett API behöver man några grundläggande komponenter:

• En webb-server där API:et kan köras, denna måste gå att nå från de klienter som skall ha tillgång till tjänsterna.
• En datakälla där informationen som applikationen jobbar med lagras och uppdateras.API:et exponerar delar av eller all denna information för klienterna. Information ligger oftast i en databas av något slag exempelvis MSSQL, MySQL, MongoDB etc.

Att använda ett API

Att använda API:er är ett mycket kraftfullt sätt att utöka en applikations funktionalitet och även ett effektivt sätt att bygga en skalbar arkitektur med återanvändbara förmågor och informationsmängder, exempelvis väderdata eller kartinformation. För att använda API:er kan följande grundprinciper användas:

1. Hitta ett API med den information som du är intresserad av, se till att det du använder är väl dokumenterat och underhållet. Exempelvis på Sveriges DataportalÖppnas i ny flik.
2. Läs igenom dokumentation och exempel på användning och utvärdera om API:et är användbart för dig. Hur man autentiserar sig för tillgång till API:er kan variera och det är viktigt att accessmetoden följs för att få åtkomst till API:et.
3. Förstå strukturen på tillgänglig information i API:et och hur API:et skall anropas för att få tillgång till denna. Verktyg som exempelvis Postman eller JQ är mycket effektiva och värda att prova då det ger möjlighet att anropa API:et och utvärdera svaren direkt i verktyget.
4. Du har nu all information för att kunna skriva koden som anropar API:et från din applikation och på detta sätt ge din applikation tillgång till API:ets information och funktionalitet.

Vad är ett REST API?

Vilka är fördelarna och varför bör det vara förstahandsvalet när man implementerar ett API?

API:er möjliggör som tidigare nämnts en integration där program, system och applikationer på ett enkelt sätt behöver kunna prata med varandra, en slags tolk som kommunikationen går genom. API:er brukar också beskrivas som ett strukturerat sätt för att överföra data från ett ställe till ett annat.

• Det behöver bli enklare och mer flexibelt att integrera API:er med varandra.
• För API:er så bör inte data vara knutet till specifika resurser och metoder. Api:er behöver också kunna returnera datat på olika format samt också kunna förändras strukturellt om man så önskar.
• API:er bör konstrueras på ett sätt som medför en okomplicerad implementation och som på ett enkelt sätt kan utnyttjas vid utbyte av information över HTTP protokollet.

REST - en kort introduktion

REST, står för Representational State Transfer och är i grund och botten en standardiserad mjukvaruarkitekturstil, som består av en speciell typ av API:er, som för branschen är känd och använd.

REST förlitar sig på ett tillståndslöst klient-serverprotokoll och i nästan alla fall kommer det att vara HTTP. Till en början förlitade sig programmerare på SOAP för att implementera API:et i webbtjänster, men på senare år har REST blivit programmerares val på grund av dess enkelhet och skalbarhet. REST gjordes för att behandla objekt på serversidan som resurser som kan skapas, uppdateras och raderas. REST kan användas av praktiskt taget alla programmeringsspråk.

Arkitekturella restriktioner

REST definierar sex stycken så kallade constraints, arkitekturella restriktioner, som behöver uppfyllas för att en webbtjänst ska kunna ses som restful.

1. Klient - Server: Denna restriktion bygger på konceptet att klienten och servern ska vara åtskilda från varandra och därmed tillåtas att utvecklats individuellt från varandra.
2. Tillståndslös: REST API:er ska vara tillståndslösa. Detta innebär att anrop ska kunna göras oberoende av varandra, där varje anrop ska innehålla all data som behövs för att fullfölja och slutföra anropet.
3. Caching: Eftersom varje anrop som görs i ett anrop ska kunna innehålla all data som behövs, så medför det också att ett REST API behöver kunna hantera större mängder data i in och utgående anrop. Därför bör ett REST API utformas så att det stödjer lagring av cache-bar data.
4. Enhetligt gränssnitt: Restriktion som är grundläggande för utformningen av alla RESTful-tjänster och som förenklar och frikopplar arkitekturen, gör att varje del kan utvecklas oberoende. Detta utan att ha applikationens tjänster eller modeller och åtgärder, tätt kopplade till själva API-lagret. Denna restriktion kan delas i fyra olika delar:
   • Resursidentifiering i anrop
   • Resursmanipulation genom representationer
   • Självbeskrivande meddelanden
   • Hypermedia för applikationstillstånd (HATEOAS)
5. Skiktat system: REST möjliggör användningen av en skiktad systemarkitektur vilket hjälper till att skapa en mer skalbar och modulär applikation.
6. Kod på begäran (optionell): Möjliggör utökning eller anpassning av funktionalitet hos en klient genom att överföra körbar kod, till exempel kompilerade komponenter som java-applets eller javascript.

Vilka är fördelarna med REST?

REST API:er är enkla och har ett standardiserat sätt att kommunicera. Du behöver exempelvis inte fundera över hur du ska formatera ditt data eller dina request varje gång du ska skicka ett meddelande.

REST API:er är skalbara och de har inget tillstånd. De är så kallade “stateless”. Med tiden så kommer din tjänst att växa och du kommer att behöva göra modifieringar. Dessa förändringar blir enkla att genomföra eftersom REST API:er är “stateless”. Det medför att du inte behöver fundera på vilket tillstånd datat har och du behöver inte heller hålla reda på det i kommunikationen mellan klient och server.

REST API:er har en hög prestanda på grund av det faktum att de stödjer "caching". Som ovan, trots att din tjänst växer och blir mer komplex, kan du bibehålla hög prestanda.

REST API:er är designade att dra fördel av befintliga protokoll. REST kan användas över nästan vilket protokoll som helst och när det används i web API:er, så dras nytta av HTTP. Detta innebär exempelvis att utvecklare inte behöver installera ytterligare mjukvara eller bibliotek för att skapa ett REST API.

Användning av REST API:er ger en hel del flexibilitet då data inte är knuten till resurser eller metoder. REST kan hantera flera typer av anrop, returnera olika dataformat och till och med förändras strukturellt med korrekt implementering av hypermedia. Denna flexibilitet tillåter utvecklare att bygga ett API som möter dina behov samtidigt som de möter behoven hos kunder med mycket varierande behov.

Korrekta implementationer av restfulla webb-tjänster medför att det blir enklare och mer flexibelt att integrera dessa API:er.

REST API:er knyter inte data till specifika resurser och metoder, har möjlighet att returnera data på olika format och kan förändras strukturellt om man så önskar.

Restfulla API:er möjliggör konstruktion på ett sätt som medför en lättviktig implementation och som på ett enkelt sätt kan utnyttjas vid utbyte av information över HTTP protokollet. Protokoll som SOAP (Simple Object Access Protocol) lämnar ett stort avtryck och är till exempel inte speciellt lämpligt vid utveckling av mobilapplikationer.

Hur kan ett REST API se ut?

Innan vi går in på djupet så behöver vi definiera vad en endpoint för ett API är för något. Enkelt uttryckt är en endpoint för ett API en URL som möjliggör att API:et kan tillgängliggöra resurser på en server och utföra sina funktioner.

Bilden nedan visar ett exempel på hur en endpoint kan se ut:

I exemplet indikeras API-delen för endpointen av /api/. Efter API-delen följer resursdelen vilket i exemplet indikeras av /foretag. Sammanfattningsvis ser vi att endpointen har en API-del samt att det finns en resurs som heter “foretag” i REST API:et

Vilka huvuddelar består ett REST API av?

• Request - Ett meddelande som skickas av klienten för att initiera en åtgärd på servern
• Response - Skickas som ett svar av servern på request-meddelandet klienten skickade.

Vad består ett Request av?

Request meddelandet är uppbyggd av flera beståndsdelar. Dels så består det av en header, som bland annat kan innehålla autentiserings-data. Det består också av en operation, som kan vara av typerna POST, GET, PUT och DELETE.

Bilden nedan visar de ingående delarna i ett request meddelande.

Visualisering av ett request-meddelandes uppbyggnad. Det består av en header som innehåller en API-nyckel/autentiseringsdata och en operation som kan vara av typerna POST, GET, PUT, PATCH och DELETE. Request-meddelandet består även av en endpoint, exempelvis http://statistik.digg.se/api/statistik, samt parametrar och body, det vill säga data som skickas med i request-meddelandet.

Bilden nedan visar ett flödesschema för ett request-response meddelande mellan en klient och server:

En klient skickar ett request (meddelande) till en server. Denna request består av en URI, http://foretag-bolagsverket.se/api/foretag?limit=2 och en GET-metod. Servern skickar därefter ett response (svar) i ett strukturerat JSON-format tillbaka till klienten.

Vad kan man göra med ett REST API?

I ett REST API finns fem grundläggande metoder som kan användas beroende på behov, dessa är:

1. GET - Används för att hämta information från API:et.
2. POST - Används för att skapa ett nytt objekt eller post i bakomliggande databas.
3. PUT - Används för att modifiera eller ersätta ett existerande objekt eller post i bakomliggande databas.
4. PATCH - Påminner om PUT men kan modifiera eller ersätta delar av ett existerande objekt eller post.
5. DELETE - Tar bort ett specifikt objekt eller post från bakomliggande databas.

Låt oss använda ett exempel för att exemplifiera hur dessa kan används.

Säg att vi har en applikation som skall integrera med sociala media plattformar typ LinkedIn, Twitter eller Facebook. Integrationen skall kunna hantera användares profil genom att läsa existerande personers profiler och artiklar som berör den unika personen.

En användare av applikationen loggar in och får en lista med nya inlägg som lagts till sedan användaren senast var inloggad. Detta kommer skicka en HTTP Request att hämta (GET) en lista med de nya inläggen. Den sociala plattformen svara då med ett JSON objekt som innehåller listan av inlägg och grundläggande information om inläggen. Applikationen kan ta denna information och presentera inläggen för användaren.

Några av inläggen intresserar användaren och för att läsa dessa så hämtas dessa inlägg i sin helhet. Detta görs genom att flera GET HTTP Requests skickas för att hämta var och en av artiklarna.

Efter att ha läst inlägg så vill användaren svara på ett inlägg, detta sker genom en POST HTTP Request som resulterar i att ett nytt objekt för svaret på inlägget skapas i databasen på den sociala plattformen.

Användaren upptäcker stavfel i sitt svar på inlägget som gjordes tidigare. Felet rättas vilket ger en PUT HTTP Request. Resultatet blir att hela objektet för det tidigare svaret byts ut mot den nya.

Ändringen på svaret på inlägget blev inte bra och användaren bestämmer sig för att ta bort svaret helt. Detta resulterar in en DELETE HTTP Request vilket tar bort objektet helt.

Vid användande av den sociala plattformen så vill användaren ändra i sin profil vilka intresseområden denna är intresserad av. Användaren kompletterar sin profil med information om att denna är intresserad av “REST API:er”. Detta resulterar i att en PATCH HTTP Request utförs för att uppdatera användarens profil, enbart uppgifterna för intresseområden för användaren uppdateras och allt annat förblir oförändrat.

Vad betyder JSON & varför använder vi det?

JSON står för JavaScript Object Notation och är förenklat ett strukturerat sätt att representera information som ser ut som JavaScript objekt.

Ett typiskt JavaScript objekt skulle kunna se ut så här:

{“person”: [
“name”: “Förnamn”,
“address”: “Efternamn”,
“pin-code”: “123456”,
“phone”: “+4670123456798”,
“email”: “fornamn.efternamn@digg.se”
]}
 

{“person”: [
“name”: “Förnamn”,
“address”: “Efternamn”,
“pin-code”: “123456”,
“phone”: “+4670123456798”,
“email”: “fornamn.efternamn@digg.se”
]}

Detta är ett förhållandevis lätt sätt att programmatiskt läsa och söka i informationen genom att den är strukturerad med taggar i värdepar (nyckel/värde). Ett värdepar betyder att nyckeln till informationen är till vänster och det värdet till höger. “Nycklarna” kommer för alla personer vara den samma medan värdet till höger varierar beroende den unika personens information.

JSON finns överallt i moderna webbaplikationer. Den är läsbar, lättviktig och fungerar mycket bra tillsammans med webbapplikationer skrivna i JavaScript då den följer samma standard. JSON fungerar dock bra i applikationer oavsett språk. Detta betyder att API:er som returnerar JSON kan användas av applikationer oavsett språk, exempelvis Java, Ruby, Python, JS, PHP, Java, C#. och många fler. Detta gör API:erna skalbara och plattformsoberoende.