API - få tillgång till bloggdata från den svenska bloggosfären

Genom att använda API:t och få tillgång till data från knuff.se så kan du erbjuda dina egna besökare ett mervärde på din egen sajt med hjälp av tusentals svenska bloggar.

Om du har en mindre blogg och bland annat vill visa vilka andra bloggar som skriver om din blogg, så är det bättre att du använder Knuffs bloggwidget istället för det mer avancerade API:t.

Allmänt

• Var snäll. Implementationer som bl.a. misshandlar knuff.se kommer att få sin tillgång till tjänsten strypt.
• Pyssla inte med fuffens. Syftet med API:t är att erbjuda dina besökare ett mervärde (ex. snabb tillgång till diskussioner om ett visst ämne). Informationen från API:t ska inte vara den enda anledningen till att besöka en webbsida (ex. tråkiga länka-till-mig-tävlingar eller MFA-sidor). Gör inte bara kopior av vad som redan finns.
• YGWYPF. Den här dokumentationen samt API:t kan när som helst ändras i framtiden. Självklart är målet alltid bakåtkompatibilitet men i vissa situationer kan det vara omöjligt. Knuff.se förbehåller även rätten att begränsa tillgång till tjänsten.
• Ange källa. Då informationen finns tack vare knuff.se eller bloggar.se så ska det tydligt anges. Om du vill använda små bilder så finns det exempel här och här.

Just nu finns det två olika sätt att använda API:t.

API-widget (javascript)

• Widgeten är förberedd för att smälta in i valfri layout. En liten inställning gör att du kan koppla bort den "inbyggda" grundlayouten och (via vanlig CSS) göra något som du tycker är snyggare.
• Widgeten visar samma blogginlägg som visas på knuff.se. Du kan alltså inte logga in någonstans för att t.ex. ta bort alltför kritiska, träffande eller välskrivna blogginlägg. Allt eller inget.
• Widgeten får visas på kommersiella webbsidor.

Grundkod

<script type="text/javascript" src="http://export.knuff.se/api/?konfigurering" charset="utf-8"></script>

Konfigurering av huvudfunktion

Konfigurering av detaljer

Exempel

Visa de 5 senaste länkarna till spreadfirefox.com/en-US/worldrecord/

<script type="text/javascript" src="http://export.knuff.se/api/?u=spreadfirefox.com%2Fen-US%2Fworldrecord%2F" charset="utf-8"></script>

Visa de 7 mest aktuella länkarna till apple.com/se/iphone/ utan grundlayout.

<script type="text/javascript" src="http://export.knuff.se/api/?u=http%3A%2F%2Fwww.apple.com%2Fse%2Fiphone%2F&c=1&s=1&n=7" charset="utf-8"></script>

Visa de 5 nyaste blogginläggen som nämner Hillary Clinton

<script type="text/javascript" src="http://export.knuff.se/api/?q=%22Hillary+Clinton%22" charset="utf-8"></script>

Implementation

Om du vill visa ett sökresultat efter ord så är det enklaste att gå till knuff.se, göra en vanlig sökning och därefter klistra in den widgetkod du hittar där. Om du vill visa länkar till en viss webbsida eller permalänk så krävs det lite mer pill. Allra enklast är om du bara vill visa blogglänkar till en enda sida - t.ex. länkar till framsidan på knuff.se - då är det bara att klistra in ovanstående kod med u satt till knuff.se (u=knuff.se)

Lite mer komplicerat blir det när du automatiskt vill visa länkar till webbsidor på deras respektive permalänkar - då måste du få ditt CMS att automatiskt skicka aktuell webbsida som ett urlencode:at argument. Den här sidan kommer att uppdateras efterhand när folk berättar (eller jag lär mig) hur man gör det i olika program.

Visa länkar till inlägg i WordPress (på egen domän)

Peta in följande kod på ett passande ställe i ditt aktuella tema (ofta raden ovanför <h2 id="comments">) i /wp-content/themes/ditt-tema-namn/comments.php

<script type="text/javascript" src="http://export.knuff.se/api/?u=<?php echo urlencode(str_replace("http://", "", get_permalink())); ?>" charset="utf-8"></script>

Visa länkar till inlägg på Blogspot

Logga in, gå till Layout och Edit HTML. Spara ner en säkerhetskopia av din mall (template). Kryssa sedan i Expand Widget Templates och leta upp <b:includable id='comments' var='post'> i textmassan.

Klistra sedan in följande kod...

<script type='text/javascript'> document.write('&lt;'+'script type=\'text/javascript\' src=\'http://export.knuff.se/api/?u='+encodeURIComponent('<data:post.url/>'.replace('http://',''))+'\' charset=\'utf-8\'&gt;&lt;\/scr'+'ipt&gt;'); </script>

...någonstans mellan <b:if cond='data:post.allowComments'> och den rubrik-tagg (t.ex. <h4>) som brukar finnas någon rad efter.

Exempel på hur det kan se ut...

Då koden endast visas på permalänk-sidorna så kan du inte använda Blogspots Preview-funktion för att se om det fungerar. Tryck Save template och besök inlägg på din vanliga bloggadress för att se widgeten.

XML/RSS-flöden

• Berätta vem du är. Skicka en vettig user-agent när du använder API:t.

Funktioner

För att få reda på adresserna till alla de olika funktionerna; kontakta Johan genom bloggar@gmail.com med en kort beskrivning av vad du planerar att göra.

• Nya länkar till en domän/webbadress. Visar endast nya länkar men med wildcard (dvs. alla nya länkar till domänen/underkatalogen/etc).
  Exempel: http://knuff.se/rss/url/mindomaen.se
• Länkar till en webbadress. Visar alla länkar knuff.se känner till (ingen tidsbegränsning) men enbart för en exakt adress.
• Blogginlägg som skriver om något speciellt. En sökning på knuff.se.
  Exempel: http://knuff.se/rss/q/%E4pplen
• Blogginlägg som använder en speciell etikett. En sökning på bloggar.se.
  Exempel: http://bloggar.se/rss/om/bananer
• Relaterade webbadresser. Andra länkar som kan antas höra ihop med en viss länk.
• Relaterade etiketter. Peta in ett nyckelord och få ut andra nyckelord som är relaterade just nu.
• Vad du vill ha. Allt går att fixa om du har ett nyttigt ändamål för informationen.

Tekniska detaljer

• Förfrågningar sker överlag genom en vanlig GET med all information i webbadressen.
• Resultat skickas tillbaka som XML (RSS 2.0 eller enklare varianter).

Exempel på data

<item>
    <title>Testinlägget (Testbloggen)</title>
    <link>http://testbloggen.tt/2008/03/17/testinlaegget.html</link>
    <guid isPermaLink="false">aamg2a88a</guid>
    <comments>http://mindomaen.se/en-speciell-adress.html</comments>
    <pubDate>Mon, 17 Mar 2008 21:10:08 +0100</pubDate>
</item>

title ger namnet på inlägget samt bloggen som kommenterar. link ger adressen till det blogginlägg som kommenterar. guid kan bl.a. användas för att rapportera felaktiga inlägg till knuff.se. comments avslöjar vilken exakt sida hos er som inlägget länkar till. pubDate anger när inlägget säger sig ha publicerats.

Exempel på en effektiv implementation för att visa länkande bloggar

Nedanstående lösning leder till en minimal belastning för alla parter. Istället för att er implementation konstant frågar om tusentals olika webbadresser har fått några nya länkar så berättar knuff.se när/om det finns någon ny information.

• Hämta ett RSS-flöde med nya länkar till domänen. Hämta ex. http://knuff.se/rss/url/mindomaen.se en gång i timman. När knuff.se hittar en ny länk från en svensk blogg till någon sida på mindomaen.se så dyker den upp i flödet. I flödet finns även information om exakt vilken sida på mindomaen.se som länkas.
• Detta RSS-flöde i sig är den enklaste implementationen. I bl.a. WordPress (instruktioner) och på Blogspot-bloggar (instruktioner) så kan detta flöde användas rakt av för att automatiskt visa länkande bloggar.
• Om du vill visa länkar till individuella webbsidor så använder du informationen från RSS-flödet (vilken sida på din domän som länkas) för att fråga en annan funktion i API:t för alla länkar till den adressen. På detta sätt frågar du knuff.se enbart om länkar till en viss webbadress när det finns minst en länk dit.
• Håll koll på vilka sidor som någon gång har länkats och uppdatera då och då länkinformationen (mha ovanstående funktion) för att t.ex. få bort ev. 404:or.