10 saker att tänka på vid skapande av API

Så du går i tankarna på att tillhandahålla ett API? Då har du kommit rätt. Jag försöker här att redogöra över de tankar jag har när det gäller det mesta vid API utveckling.

Först och främst så bör du ställa dig frågan om ett API verkligen är rätt, och i de flesta fall så skulle jag säga att API är rätt väg. De fall då ett API kanske inte är lämpligt är då din tjänst enbart bygger på ett annat API och ej tillför något mervärde. Prioritering är också en viktig punkt, i flertalet fall så kan det tillåmed vara så att ett API skall finnas innan en webbsida finnes (framförallt i offentlig sektor).

Om du tillhandahåller en iPhone-app eller någon annan typ av extern tjänst så är detta också tillämpningsbart.

1. Placera ditt API under ett eget DNS-namn, exempelvis api.domän.se. Även om api.domän.se pekar till domän.se till en början.

2. Detta har med ovan punkt att göra: Exportera din data till en separat server som exempelvis ligger i molnet. Detta för att enkelt göra ditt API redundant och icke beroende av din ordinarie tjänst som kanske får problem om du får tusentals API-förfrågningar per sekund. Kan dock bli problem med realtidstjänster om API:et tillhandahåller sekundaktuell information.

3. Fundera om du bör tillhandahålla en krypterad version över HTTPS. Fundera även över om anrop bör vara signerade, för https i sitt standardutförande verifierar ej klient, bara server. Självklart kan du köpa SSL-certifikat via min sajt https.se.

4. Vilket format är lämpligast. JSON REST, XML SOAP eller annat? Jag rekommenderar REST JSON. Se Google eller FRAPI

5. Vill du hålla koll på vilka som anropar ditt API? Då bör du tillhandahålla en API-nyckel och bygga en registreringsprocess för detta. Enklast är att använda Google Forms. Det finns ofantligt många sätt att bygga detta förfarande.

6. Du bör införa kontroll av anrop samt begränsningar. Detta kan vara bra för att förhindra miljontals anrop i sekunden eller forcering av lösenord/användarnamn. Begränsa förfrågningar på så mycket som du bara kan, exempelvis IP-nummer.

7. Vilken licens kan användas? Här kan myndigheter få problem då CC-licenser kan gå emot lagstiftning. E-delegationen håller på med ett arbete om bl.a. detta och kommer att tillhandahålla mer information.

8. Upprätta en changelog, blogg eller E-postlista (Google Groups) för att berätta om eventuella förändringar. Här kan det även vara bra att prefixa alla API-anrop med versionsnummer för att bibehålla bakåtkompabilitet. Exempelvis: api.domän.se/v1/anropstyp

9. Glöm framförallt inte att erbjuda dokumentation och kod-exempel på hur API:et används. Berätta om innehållet, begränsningar, datatyper, relationer, statuskoder osv. Kanske ett forum för frågor? Wiki? Status-sida för att berätta om eventuella problem med ditt API eller fördröjningar. Se Pingdom eller Watchmouse.

10. Övriga punkter: Länka till de som använder ditt API för att uppmuntra användning. Ta betalt för ditt API? Berätta för Mashup.se att du har ett API. Hur länge bör du cacha? Pagination, page=1 vs.  cursor: start_id=1234. Loggning? If-Modified-Since header?

That’s it! Har säkert glömt många bra saker, skriv en kommentar och berätta vad du saknar.

5 reaktioner på ”10 saker att tänka på vid skapande av API

  1. Bra inlägg! Kort, tydligt och matnyttigt. Flattrad! Får man önska innehåll på kommande blogginlägg så skulle jag gärna läsa om hur du byggt upp dina APIer, vad du skulle gjort annorlunda och vad som funkat bra. Tack för en riktigt intressant blogg!

  2. Har du någon bra lista över intressanta API:er som man kan bläddra igenom? Tror säkert man kan komma på massa bra ideer bara genom att bläddra igenom en sån :)

Kommentera

E-postadressen publiceras inte. Obligatoriska fält är märkta *