API – vad är det

API står för Application Programming Interface. Det är ett gränssnitt som tillåter olika mjukvarusystem att interagera med varandra.

Exempel på användning

Din webbläsare, din server, din programvara kan lämna och hämta information från olika servrar på nätet.
Till exempel kan du anropa Open Weather map med en enda URL:

https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude={part}&appid={API key}

Du får fylla i latitude och longitude och regisrera dig för en gratis API-nyckel. Sedan får du fråga 2000 gånger om dagen.

Rent praktiskt

Du kan surfa till en hemsida som kör Javascript kod, som i sin tur hämtar en väderprognos från en väder-server på nätet och uppdaterar hemsidan med en del av datat.
Du kan surfa till en hemsida och när sidan hämtas från servern passar servern på att kontakta en väder-server och hämtar väderprognosen och bäddar in datat i hemsidan innan du får den.

Översikt

Det här är en jämförande tabell för några vanliga teknologier.

Beskrivningar

REST (Representational State Transfer)

Använder standardiserade HTTP-metoder som GET, POST, PUT och DELETE för att anropa servern.
Du skickar antingen GET parametrar i webbadressen eller JSON in POST.
Du får tillbaka JSON data och en statuskod. Har inget schema. Du behöver titta i APIets dokumentation för att se vad den förväntar sig.

Läsa om REST

GraphQL

Detta är ett frågespråk för API:er som låter klienter begära den data de behöver ner på fältnivå.
Har en enda URL. Använd GET för att få schemat. Sätt ihop en fråga i JSON format och skicka en POST till samma URL.
Du får tillbaka en JSON och en statuskod 200.

Läsa om GraphQL men se också längst ned i det här dokumentet för en enkel beskrivning.

gRPC: Remote Procedure Call

Ett ramverk som är öppen källkod och högpresterande. Skickar binär data vilket är mer effektivt men att människor inte kan läsa det.

Läsa om gRPC

Förenkla

Om du vill hålla dig till standard kan du ändå utesluta delar av REST och GraphQL och bestämma hur namngivning ska vara.

Eget API

Du kan designa ditt eget API med utgångspunkt från REST. Till exempel kanske du bestämmer dig för:
Endast en URL. Alltid POST. Alltid JSON. Alltid status 200 även vid fel. JSON ska vara en array med kommandon.

Köra mot API med GET

Att köra mot ett REST-API med GET är enkelt. Du behöver en webbläsare och i URLen skriver du alla parametrar.
Till exempel när du söker med DuckDuckGo kan din URL se ut så här:

https://duckduckgo.com/?t=h_&q=London&ia=web

En domänadress, ett ? och sedan parametrar separerade med &.

Fördelen med GET är att du kan göra ett bokmärke av all data i din webbläsare.

https://www.booking.com/city/gb/london.sv.html?aid=352068&pagename=city-london&label=msn-x*0799R*gMQLBKb47Ed0Dg-80058350707993:tikwd-80058504035172:loc-174:neo:mte:lp153565:dec:qsLondon&utm_campaign=United%20Kingdom&utm_medium=cpc&utm_source=bing&utm_term=x*0799R*gMQLBKb47Ed0Dg&msclkid=34f9fd6707581babb1bd953886e10d3d&utm_content=London%20-%20UFI%3A-2601889

Men det ser för eländigt ut i URLen.

En annan intressant sak ser du i domänadressen: booking.com/city/gb/london.sv.html?
Delar av datat finns efter domänen men före ?
Webbservern kan antingen läsa från den katalogen på webbserverns hårddisk, eller så kan man bestämma att allt kommer till webbservern och där får man plocka isär URLen och hämta ut all data.

GET kan skicka tillbaka stora mängder data. Då ser du ett stort dokument i din webbläsare med XML data eller JSON data.

Du kan använda REST i alla populära språk, exempel: Javascript, eller i PHP.

Köra mot API med POST

Man använder POST för att kunna skicka stora mängder data.

Ska du vill testa lite REST med POST eller GraphQL som alltid kör POST då blir det lättare att använda ett verktyg som Postman.

Enklast är att ha all data i en enda klump och koda den med JSON. Men som alltid går det att peta in data lite överallt.

GraphQL

Huh måste man ha ett ramverk på klienten och ett ramverk på servern? Nej verkligen inte.

Vill du prata med en server som kör GraphQL skapar du en POST med JSON data och skickar den till serverns enda URL. I din data finns namnet på den funktion du vill köra.
Hur meddelandet ska se ut finns beskrivet i schemat som du når från din webbläsare med samma URL.

På servern får du en POST med JSON data och kan plocka ut alla in-variabler, namnet på funktionen och beskrivningen vilka fält som klienten vill ha.
Nu kan du sätta ihop datat så det är formaterat efter önskemålet, JSON komprimera och göra en echo på JSON strängen. Klart.

Med ett ramverk på klienten kan du få cachening av dina frågor och svar.

Med ett ramverk på servern kan du få dina inkommande POST jämförda mot schemat och avfärdade om de inte stämmer. Du får din ut-data skrubbad så den bara innehåller den data som klienten frågat efter. Du får kontroll av ut-datats data typer, och kontroll att de fält som enligt schemat alltid ska innehålla data verkligen gör det.

Exempel på GraphQL ramverk

gRPC

Jag kan tyvärr inget om gRPC. Har aldrig använt det. Det som lockar är effektiviteten att det är binär dataöverföring.

Slutsats

Använd REST om du vill:

• ha en enkel implementation utan ramverk
• överföra stora datamängder till klienten
• kunna ha lookup-tabeller
• både ut-data och in-data är ofta läsbar text om du inte krypterat

Används med fördel i integrationer, webbapplikationer, appar.

Använd GraphQL om du vill:

• ha exakt den data du frågar efter
• minska antalet frågor mot servern med cache och kunna ha fler frågor i samma anrop.
• slippa uppdatera en dokumentation nu när du har ett schema
• ha koll på alla datatyper med schemat

Används med fördel i webbapplikationer, appar.
GraphQL kollar varenda fält mot schemat innan det skickas till klienten. Det är olidligt långsamt på stora datamängder. Därför ska du inte använda GraphQL på integrationer som ofta skickar mycket data. Alternativt kan du skippa ut-kontrollen men då kan du lika gärna köra REST.