Information om Kundo:s API

Kundo tillhandahåller ett API som gör det möjligt att hämta ut och presentera information på er webbplats eller i annat externt system.

Följande data går för närvarande att hämta via Kundo:s API:

• Samtliga inlägg i ett forum
• Inlägg filtrerade efter frågor, problem, förslag och beröm
• Populära inlägg
• Detaljer för ett givet inlägg
• Alla kommentarer för ett givet inlägg
• Alla dialoger som innehåller ett visst sökord

Det går också att posta till sitt forum på Kundo, t.ex. om man vill bygga ett helt eget tyck till-fönster som postar till sitt forum. Två metoder stödjs för att göra detta:

• Posta ett inlägg via JSON
• Posta ett inlägg med ett HTML-forumlär

Följande övriga metoder finns tillgängliga:

• Hämta och posta privat data med API-nyckel
• Hämta information om ett forum
• Anmäla inlägg och kommentarer som olämpliga

I exemplen nedan används Kundo:s eget forum. För att hämta ut data ur ett annat forum behöver du byta ut "kundo" i exemplen nedan mot rätt slug för det aktuella forumet. http://kundo.se/org/slug/ - Exempelvis http://kundo.se/org/bokus/.

Vårt API utvecklas löpande. Har du önskemål om ny funktionalitet är du välkommen att kontakta oss!

Hämta data via API:et (Alla exempel är klickbara)

http://kundo.se/api/kundo.json

Alla inlägg som ni fått (maximalt 50 - se paginering nedan).

http://kundo.se/api/kundo/question.json

Alla frågor som ni fått (maximalt 50 - se paginering nedan). På motsvarande sätt hämtas problem (problem), förslag (suggestion) och beröm (praise) ut.

http://kundo.se/api/popular/kundo/question.json

Era mest populära frågor just nu (maximalt 50 - se paginering nedan).

Varje API-anrop returnerar en address (<uri>) som indikerar vilket anrop som ska göras för att få ut mer detaljer om ett givet objekt.

http://kundo.se/api/dialog/kundo/1.json

All information vi har om inlägget med id=1.

På liknande sätt kan även kommentarer till ett visst inlägg hämtas ut.

http://kundo.se/api/comment/kundo/1.json

Alla kommentarer som finns till inlägget med id=1 (maximalt 50 - se paginering nedan).

Det går även att söka på ett eller flera nyckelord.

http://kundo.se/api/search/kundo/hello%20world.json

Sök bland alla inlägg som innehåller "hello world". Returnerar maximalt 10 inlägg.

Viss information om själva forumet, så som statusmeddelande, välkomsttext och forumets namn kan vara relevant att hämta via API:et.

http://kundo.se/api/properties/kundo.json

Information om egenskaper på själva forumet.

Här är de egenskaper som kan fås ut idag:

Tillgängliga returformat

Kundo:s API hanterar returformaten XML, JSON, och JSONP. Genom att anpassa respektive anrop kan XML returneras istället. Exempelvis:

http://kundo.se/api/kundo.xml

Alla inlägg som ni fått, i XML-format.

http://kundo.se/api/kundo.json

Alla inlägg som ni fått, i JSON-format.

http://kundo.se/api/kundo.json?callback=your_own_method

Alla inlägg som ni fått, i JSONP-format, där [your_own_method] är den javascriptmetod som ska anropas.

Paginering

Varje anrop returnerar maximalt 50 inlägg baserat på den sortering du angett (se nedan). För att hämta ut nästa omgång inlägg lägger du till parametern start=50, start=100 osv.

http://kundo.se/api/kundo.json?start=50

Hämta nästa 50 inlägg

Sortering

Inläggen och kommentarer sorteras som standard i omvänd kronologisk ordning, dvs den senaste först. Genom att skicka med en valfri tillgänglig paramter kan sortering ske efter dessa. Exempelvis kan du sortera inläggen efter antal kommentarer:

http://kundo.se/api/kundo/q.json?sort=num_comments

Alla frågor som ni fått, sorterade efter antalet kommentarer. Minst antal först.

För omvänd sortering, lägg till ett minustecken ("-") framför.

http://kundo.se/api/kundo/q.json?sort=-num_comments

Alla frågor som ni fått, sorterade efter antalet kommentarer. Flest antal först.

Tillgängliga sökparametrar är:

Posta data via API:et

För att det ska vara möjligt att göra avancerade anpassningar av tyck till-fönstret är det också möjligt att posta inlägg, kommentarer och röster via API:et.

http://kundo.se/api/kundo

URL att posta inlägg i ditt forum.

http://kundo.se/api/comment/kundo/1

URL för att posta kommentarer till en specifik dialog.

http://kundo.se/api/vote/kundo/1

URL för att posta röster till en specifik dialog.

Data skickas antingen som JSON med Content-Type satt till application/json, eller som en HTTP POST med all data som behövs som forumlärdata.

Skicka data som JSON

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
    "topic": "Q",
    "title": "Post title",
    "text": "Post contents..."
}

Exempel på postning av dialog i form av JSON.

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
    "text": "My comment goes here..."
}

Exempel på postning av kommentar i form av JSON.

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
}

Exempel röstning i form av JSON.

Om du har tillgång till cURL kan du exempelvis testa anropet såhär:

curl -i -H 'Content-Type:application/json' -X POST -d '<Your JSON data here>' http://kundo.se/api/kundo

Testa att posta data till API:et med cURL.

Svarskoder (HTTP)

Eventuella felmeddelanden rapporteras på följande sätt:

HTTP/1.1 400 BAD REQUEST
Content-Type: text/plain
...

Bad Request

HTTP-svar för felaktigt formaterad JSON-data.

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
...

{
    "text": [
        "Du m\u00e5ste skriva in en beskrivning."
    ],
    "useremail": [
        "Du m\u00e5ste fylla i din e-postadress."
    ],
    "name": [
        "Du m\u00e5ste fylla i ditt namn."
    ],
    "title": [
        "Du m\u00e5ste skriva en rubrik."
    ]
}

Obligatorisk data saknas. Nyckeln indikerar vilket fält som är felaktigt, och felmeddelandet förklarar vad som är fel.

HTTP/1.0 409 CONFLICT
Content-Type: text/plain
...

Conflict/Duplicate

HTTP-svar om inlägg med exakt samma titel och text redan finns.

Om allt går bra skickas svar på följande sätt:

HTTP/1.1 201 CREATED
Content-Type: text/plain
...

Created

Inlägget skapades utan problem.

Skicka data via ett HTML-forumlär

API:et stödjer också att man postar forumlärdata direkt till det.

<form action="http://kundo.se/api/kundo" method="POST">
    <p>
        Type of question:
        <select name="topic">
            <option value="Q">Question</option>
            <option value="P">Problem</option>
            <option value="S">Suggestion</option>
            <option value="B">Praise</option>
        </select>
    </p>
    <p>Title: <input name="title"></p>
    <p><textarea name="text"></textarea></p>
    <p>Your name: <input name="name"></p>
    <p>Your e-mail: <input name="useremail"></p>
    <p><button type="submit">Send</button></p>
    
    <input name="error_url" value="<URL to forward errors to>" type="hidden">
    <input name="success_url" value="<URL when successfully posted>" type="hidden">
</form>

Exempel på postning av data i form av forumlärdata.

De två sista fälten, error_url och success_url, har att göra med felhantering:

• Om alla fält fylls i korrekt skickas användaren till success_url
• Om ingen success_url skickats med skickas användaren till sin dialog
• Om något fält är felaktigt skickas användaren till error_url, och felmeddelande läggs till som GET-parametrar på URL:en. T.ex:
  http://example.com/feedback?text=Du+måste+skriva+in+en+beskrivning.&
useremail=Du+måste+fylla+i+din+e-postadress.
• Om någon av error_url och success_url är felaktiga visas ett felmeddelande

Hämta och posta privat data med API-nyckel

Det är även möjligt att hämta ut data som enbart är tillgänglig för inloggade redaktörer via Kundo:s API. För att hämta ut denna typ av data behöver ni en API-nyckel, tillgänglig för kunder med ett konto av typen Integrate eller speciellt avtal. Kontakta oss om ni önskar få en egen API-nyckel.

Hämta inlägg med en viss tagg

http://kundo.se/api/tag/kundo/exempel.json?key=fakekey123

URL att för att hämta ut inlägg taggade med "exempel" för ett givet forum. En felaktiv API-nyckel ger felkoden 401 "Authorization Required"

Hämta information om ett forum

Viss information om själva forumet, så som statusmeddelande, välkomsttext och forumets namn kan vara relevant att hämta via API:et.

http://kundo.se/api/properties/kundo.json

Information om egenskaper på själva forumet

Anmäla inlägg och kommentarer som olämpliga

http://kundo.se/api/report-dialog/kundo/1

URL för att anmäla en dialog som olämplig

http://kundo.se/api/report-comment/kundo/1

URL för att anmäla en kommentar som olämplig

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
    "report_reason": "Report reason goes here..."
}

Exempel på anmälan av dialog eller kommentar i form av JSON.

Vårt API utvecklas löpande. Har du önskemål om ny funktionalitet är du välkommen att kontakta oss!