all our base are belong to you

API Dokumentation

  1. Introduktion
  2. Autentisering
  3. Format
  4. Svar och fel
  5. Bilder
  6. Paginering
  7. Versionshantering
  8. Wrappers och exempel
  9. Booliloggan
  10. Vilka använder API:et?
  11. API version 1

Introduktion

Boolis API ger dig en möjlighet att få åtkomst till Boolis data och interagera via tredjepartsapplikationer. API:et följer principerna för REST. I den här guiden och i utforskaren hittar du förhoppningsvis allt du behöver för komma igång. Skulle du har några frågor eller stöta på problem så kan du kontakta oss här.

I vårt användaravtal finns information om hur man får använda API:et. Utöver det legala så uppskattar vi om du kodar med ansvar :) Gör inte onödigt många requests, cacha lagom länge, berätta vem du är genom att använda lämpliga headers, User-Agent och Referrer. I vissa fall kan vi göra undantag från avtalet, kontakta oss om du är intresserad av att veta mer om detta.

Frågor och diksussioner passar utmärkt här. Vid större uppdateringar och ärenden utöver det vanliga kommer vi att skicka e-post. Vi lovar att inte bli spammiga!

Autentisering

Alla anrop autentiseras genom parametrarna callerId, time, unique och hash som skickas med i frågan. Ett exempel på hur en fråga till API:et kan se ut visas här:

http://api.booli.se/listings?q=nacka&limit=3&offset=0&callerId=\
		[callerId]&time=1323793365&unique=3116053465361547264\
		&hash=a053d19fcced8e180df1a40b3fc95b6560eee1af

callerId är det namn du angav då du registrerade dig.

time är en UNIX timestamp.

unique är en 16 tecken lång sträng som slumpgenereras för varje förfrågan, t.ex. ”f4508htyuk98fe4f”.

hash är en sha1hash sha1(callerId + time + key + unique) som en 40-char hexadecimal, t.ex. ”6b76a4ede12897d42dabc2a5f9270bbdb76985af”, där key är den privata nyckel du tilldelats.

Format

Det svarsformat som finns tillgängligt är JSON, enligt application/json, kodat som UTF-8. Det formatet ska alltid specificeras i frågans Accept header. Ett exempel, med curl:

curl -H 'Accept: application/vnd.booli-v2+json' \
		http://api.booli.se/listings?q=nacka[autentisering]

Svar och fel

Svarskoden finns alltid i svarets header. De svar som finns är:

  • 200 OK: Allt gick bra (gäller GET, PUT, eller DELETE).
  • 201 Created: Skapad (gäller POST).
  • 400 Bad Request: Frågan var inte giltigt utformad.
  • 403 Forbidden: Autentiseringen misslyckades.
  • 404 Not Found: Frågan ställdes till en resurs som inte finns.
  • 405 Method Not Allowed: Ej tillåten metod (t.ex. försök till att skicka en POST till en URL som bara accepterar GET).
  • 406 Not Acceptable: Servern kan inte uppfylla kraven från frågan (dessa ställs med Accept-headern).
  • 500 Internal Server Error: Något gick fel hos Booli.
  • 503 Service Unavailable: API går för tillfället inte att nå.

De flesta frågor som resulterar i felkoder (4XX eller 5XX) innehåller ytterligare kort information om vad som gick fel.

Bilder

På grund av rättighetsskäl får endast en mindre bild, s.k. thumbnail visas upp i de applikationer som använder API:et. URL till bilden byggs upp enligt:

http://api.bcdn.se/cache/primary_[booliId]_[width]x[height].jpg

booliId är det id som unikt representerar en bostadsannons i API:et. width och height anger bildens dimension i pixlar och får max vara 140 respektive 94.

Paginering

För att minska mängden information som skickas vid varje svar finns en system för paginering. Följande attribut skickas med som hjälp:

{
	"count": 23, // Antalet som skickades
	"totalCount": 48, // Det totala antalet som finns tillgängligt på servern
	"offset":   25,  // Från vilket position resultaten ska hämtas
	"limit":  25,  // Max antal som skickas tillbaka från servern
}

Det vanliga är att första frågan har offset=0 samt limit satt till något som passar applikationen, den får dock inte överstiga 500 som är högsta tillåtna gräns. För att sedan hämta efterföljande bostadsannonser i nästa fråga så sätter man offset till det värde man har på limit och lämnar limit orörd. count och totalCount finns med som stöd vid presentation.

Versionshantering

API:et kan komma att uppdateras. Vi kommer inte att uppdatera namn på resources, däremot kan vi lägga till attribut och underresurser. Vill du frysa din applikation till en viss API-version är det möjligt, men det är inte något vi rekommenderar. Detta görs genom att sätta tidigare nämnd Accept-header till application/vnd.booli-v2+json. Exempel:

curl -H 'Accept: application/vnd.booli-v2+json' \
	http://api.booli.se/listings?q=nacka[autentisering]

Wrappers och exempel

Externa hjälpmedel som kan underlätta användandet av API:et.

Några Gists för att komma igång:

Enligt vårt användaravtal ska en Booli-logga visas vid användande av API:et och den finns att ladda ner här som .png, .ai eller .eps.

Vilka använder API:et?

Här är några exempel på vad man kan göra med API:t, och här vill vi såklart presentera din tillämpning av API:et, så säg till när det är klart!

API version 1 [DEPRECATED]

Dokumentation för API version 1 hittar du här.

Det finns även ett par wrappers skrivna till första versionen av API:et. Varför inte forka? :)

Python wrapper - av Filip Salomonsson

PHP wrapper - av Erik Pettersson