Etikettarkiv: XML

Bloggsök API version 2

Efter en hel del strulandes och ett fallskärmshopp senare så är nu API:et för bloggsökningen uppe igen och snurrar med en hel del nya härligheter.

För att sammanfatta:

  • Booleansökningar med AND samt OR.
  • Cache-Control sätts nu i HTTP-headers till en timme.
  • Möjlighet att enbart visa antalet träffar vilket minskar belastningen i onödan.
  • XML kommer att skrotas till förmån för enbart JSON.
  • Bloggtrend API där du kan söka på godtyckligt ord och få upp antalet träffar grupperat på datum. Sträcker sig lite olika långt tillbaka i tiden beroende på antalet träffar.
  • Kommer snart: Blogglänk-API för att skapa fina länkgrafer eller om du vill se hur många, eller vilka bloggar som länkar till en viss blogg eller tidningsartikel. Detta API använder exmepelvis BloggVärde för att försöka räkna ut hur populär en blogg är.
Beskrivning av de nya funktionerna enligt följande:

Bloggtrend API

Anropas på följande sätt:

http://api.bloggz.se/api.json?q=midsommar&type=trends

Vilket då returnerar en JSON som ser ut ungefär så här (gissa vilken dag midsommarafton inträffade 2011)

Enbart antalet träffar

Om du enbart vill returnera antalet träffar för en sökfråga utan annat innehåll så slänger du på &type=hits på följande sätt:

http://api.bloggz.se/api.json?q=smsl%E5n&type=hits

Se även mitt blogginlägg om Bloggsök API version 1.

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.