Iteam
GitHub

15 viktiga saker att tänka på när du bygger ett bra API

Varför API?

Varje organisation har förr eller senare behov av ett eget API. API står för Application Programming Interface och förenklat kan man säga att det är en del av er officiella hemsida som är byggd för att datorer och utvecklare ska kunna komma åt dina tjänster och information på ett standardiserat och förenklat sätt.

Ett bra API gör att du enkelt kan få nya samarbetspartners som hjälper dig att sälja eller sprida din information. Istället för att länka användare mellan olika sajter kan nämligen ett API göra att informationen kan sammanställas och presenteras på ett ställe. Ett bra exempel på detta är fastighetsmäklare som tidigt har använt system med API som gör att Hemnet och andra kan visa en samlad och komplett lista över lediga lägenheter och hus. Om du sitter på information som du tror att fler skulle ha nytta av att använda är det dags för dig att bygga ett API. Det kan öppna nya affärsmöjligheter för dig att tjäna pengar på din information eller tjänster.

Det viktigaste när man ska bygga ett bra API

  1. Skriv en tydlig och komplett dokumentation med exempelkod samt exempel på de svar man får tillbaka. Dokumentationen skall vara tillgänglig online, vara skriven på engelska och vara publik så att den blir sökbar via Google. Även om inte alla ska ha tillgång till ditt API är det ingen nackdel att man kan referera till den utan inloggning
  2. Välj rätt teknik. Om du har utvecklare inom flera teknikområden (tex javascript, .NET, PHP, iOS och Java) väljer du REST (http://wikipedia.org/wiki/REST) och endast om du har själv kontroll på både API och anropare väljer du SOAP. 
  3. Hitta en bra säkerhets- och autentiseringsmekanism. Om du har en Windows-miljö och endast några enstaka användare/anropare kan du använda NTLM och Active Directory. Om du har många användare/anropare väljer du oAuth. Bygg in samma säkerhetsfiltrering av det data du levererar i ditt API som övriga webbplatsen.
  4. Namnge alla anrop på engelska. Även om du bara har alla anropare i Sverige så är chansen stor att de ändå skriver sina program på engelska och då sticker ditt API ut. Använd hellre substantiv än verb så länge det går. D.v.s., istället för GetOrdersForUser?Id=15 kan du namnge ditt anrop som /orders/?userId=15 det minskar antalet metoder och gör det lättare att förstå omfattningen av ditt API.
  5. Inkludera pagineringsstöd, dvs skicka endast en sida i taget men gör det möjligt för anroparna att bestämma storleken på varje sida och skicka alltid med totala antalet träffar. Skicka pagineringsstödet som del av anropen t.ex. start=0, limit=15.
  6. Välj en enkel URL som du inte kommer ändra och se till att inkludera versionsinformation så att du kan tillåta dig själv att göra ett nytt gränssnitt om du väljer att bygga om detta senare. T ex: api.dittforetag.se/v1
  7. Skapa testknappar för dina anrop direkt i dokumentationen så att man kan verifiera att anropen fungerar och ger det man förväntar sig. 
  8. Kontrollera att du använder en modern encoding. Använd helst UTF-8 eller UTF-16 även om ditt data är i ett annat format i lagring är det dags att börja konvertera detta till dina kunder.Man måste kunna läsa svaren även som människa.
  9. Låt anroparen välja leveransmetod (t ex XML ellers JSON) som en del av anropet. T ex: api.dittforetag.se/v1/users.json eller api.dittforetag.se/v1/users.xml
  10. Håll koll på vilka som använder ditt API. Be anroparna ansöka om en API-nyckel mot deras emailadress. På det sättet kan du enkelt stänga av anropare som använder ditt API på fel sätt och du kan även skicka ut information om viktiga förändringar.
  11. Hello World – koncentrera dig på att alla som läser din dokumentation ska förstå och kunna bygga den enklaste användningsområdet av ditt API. Då kommer man över tröskeln och kan ta till sig av den mer avancerade funktionaliteten lättare.
  12. Tänk på hastigheten och /Driftsäkerheten. Varje del av ditt api måste vara effektivt byggt för att dina anropare ska våga använda det. Om ditt API upplevs som långsamt eller instabilt kommer även dina samarbetspartners sajter bli långsamma och instabila. Testa också att du klarar av många användare med t ex LoadImpact (http://loadimpact.com). 
  13. Se till att inga anrop behöver ske i en viss ordning. Detta kallas "stateless" och innebär i vanligaste fall att man skickar med autentiseringsanropen i samma anrop som de vanliga anropen så att servern inte behöver hålla denna information i sessioner. För anroparna innebär detta att ditt API alltid kommer svara på samma sätt och för dig innebär det att du enklare kan skala din hårdvara.
  14. Använd standardiserade felkoder men skicka även med en förklaring i text på vad som hänt. Använd gärna felkoderna från HTTP protokollet. T ex: 200 = OK, 404 = not found, 403 = authentication error, 500 = server error och skicka felmeddelandet som ett objekt serialiserat med den metod du/anroparen har valt.
  15. Använd bara framtidssäkra och öppna format, inte stängda proprietära format. Dvs undvik Excel, PDF eller Word. Om du ska packa ihop flera svar i samma svar, skicka då hellre en lista på URLer till de filer du vill bifoga än att packa ihop dem som filer i ett ZIP paket. 


Tänk lagom stort från början

En lustig sak med API:er är det från början kan vara svårt att förutse vilka som kommer använda ditt API och vad de kommer använda för information. Oftast börjar behovet med ett konkret case. Kanske är det en specifik partner som behöver ha ett "enkelt API" för att komma åt en viss typ av information och då är det lätt att fokusera för mycket på den första användaren för mycket så att man missar att det kan vara flera andra som behöver samma typ av information men med ett annat fokus. Därför är det värt att stanna upp lite och fundera på vad du har som andra kan vara intresserad av att använda innan du börjar utveckla.

Därefter finns det en del missar som man kan hamna i och tyvärr är det väldigt svårt att byta teknik när man väl har valt teknik en gång. Det är ju nämligen inte bara du som behöver investera tid och pengar i denna koppling så när dina partners har gjort klart sin integration mot dig är det synd att tvinga dem att byta teknik bara för att du gör det. Sen ska man inte överdriva, börja med det du vet men försök att möjliggöra för att utöka ditt API framöver utan att gamla anropare slutar fungera.

Många nya företag har blivit populära på senare år har blivit det mycket på grund av att de har ett frikostigt API. Bra exempel på detta är:

  1. Facebook
  2. Flickr
  3. Paypal
  4. Google Maps (eller hela Google kan man säga)

Några konkreta tips på API:er (några finns och andra är tips på vad som borde byggas):

  1. Postens brevlådor, serviceställen, postnummer, uppslagning av orter, postnummer konvertering till GPS positioner.
  2. Banken, få tillgång till egna konton, saldo etc via säkert API
  3. Redovisningsbyrån bör erbjuda sina kunder ett enkelt sätt att skicka in tidredovisning, kvitton, fakturor etc via API
  4. Reseföretag bör erbjuda API för att låta parters bygga och sammanställa olika resealternativ
  5. Bildbyråer kan erbjuda API för bildsökning i deras bilddatabas och erbjuda integration mot t ex CMS system eller trycksaksproduktion
  6. Tryckerier kan göra enkla API för att beställa nya visitkort till en organisation
  7. Översättningstjänster kan leverera API för beställningar och leverans av översättningar

Om du använder JSON i ditt API är följande Chrome extension ovärdeligt.

Tips: Ladda ner JSONView https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc 

Christian Landgren
2011-06-27