CUM API

CUM API är alltså API:et till CUM. Och tro det eller ej så finns det någon form av version av detta tillgängligt, redan. Denna sida samlar dokumentation av API:et så att godtycklig hacker kan hacka fram ett klientbibliotek. Det här är inte så värst fin dokumentation, men vi får väl jobba på det.

Saker att komma ihåg

• UTF-8-kodning
• ...

Grundstruktur

Klient

Ett call till CUM's API ser ut såhär:

<cum>
  <apiKey>%apiKey%</apiKey>
  <command>%kommando%</command>
  <params>
    ...
  </params>
</cum>

Om man t.ex. vill kontrollera en användares användarnamn och lösenord mot API:et kan ett riktigt call se ut:

<cum>
  <apiKey>a3b4b2F2C2hg3ifs7</apiKey>
  <command>auth</command>
  <params>
    <username>användarnamn</username>
    <password>md5-summa-av-lösenord</password>
  </params>
</cum>

Server

Serversidans XML-svar är snarlikt, och är på formen:

<cum>
  <responseCode>%responseCode%</responseCode>
  
  [<result>
    ...
  </result>]
</cum>

Som svar på ovanstående klientsnutt skulle man t.ex. kunna få som svar:

<cum>
  <responseCode>102</responseCode>
</cum>

som talar om att lösenordet är felaktigt.

Returkoder

Globala returkoder

Serversidan svarar alltid med en returkod. Det finns några "globala" returkoder, som följer i listan nedan:

• INVALID_APIKEY - API-nyckeln är felaktig, d.v.s. värdet %apiKey% är felaktigt.
• INPUT_ERROR - Servern kunde inte tolka data du skickade, vilket förmodligen beror på felaktig XML-kod eller felstavade saker.

Vid dessa felmeddelanden medföljer inget <result>...</result>, utan endast vid returkoder markerade med grön färg.

Returkodsöversättningstabell

Här är en tabell som översätter siffror till namn och vice versa, om man så vill.

Returkodsöversättningstabell
Namn	Kod
INVALID_APIKEY	100
AUTH_SUCCESS	101
AUTH_INVALID_PASSWORD	102
AUTH_INVALID_USERNAME	103
OK	111
NO_DATA	112
INPUT_ERROR	200

Kommandon

%apiKey% är rakt igenom din API-nyckel.

auth

Skickar en begäran om autentisering av en användare.

Struktur

<cum>
  <apiKey>%apiKey%</apiKey>
  <command>auth</command>
  <params>
    <username>%username%</username>
    <password>%password</username>
    [<persistent>1</persistent>]
  </params>
</cum>

Params

• %username% - Användarnamnet som skall kontrolleras.
• %password% - MD5-summa av lösenordet för användaren.
• persistent - Om given, talar om för API:et att skapa en persistant session.

Returvärden

• AUTH_SUCCESS - Både användarnamn och lösenord är korrekta, användare följer.

<cum>
  ...
  <result>
    <user>
      <id>%id%</id>
      <username>%username%</username>
      <email>%email</email>
      <displayname>%displayname</displayname>
      <lastlogin>%lastlogin%</lastlogin>
    </user>
    [<sessionid>%sessionid%</sessionid>]
  </result>  
</cum>

• AUTH_INVALID_PASSWORD - Användaren finns men lösenordet för denna användare är felaktigt.
• AUTH_INVALID_USERNAME - Användaren finns inte.

userlist

Skickar förfrågan om en lista på alla användare och returnerar (oftast) en sådan lista. Eh.

Struktur

<cum>
  <apiKey>%apiKey%</apiKey>
  <command>userlist</command>
</cum>

Params

Uppenbarligen inga..

Returvärden

• OK - Användarlista följer.

<cum>
  ...
  <result>
    <user>
      <id>%id%</id>
      <username>%username%</username>
      <email>%email</email>
      <displayname>%displayname</displayname>
      <lastlogin>%lastlogin%</lastlogin>
    </user>
    ...
    <user>
      <id>%id%</id>
      <username>%username%</username>
      <email>%email</email>
      <displayname>%displayname</displayname>
      <lastlogin>%lastlogin%</lastlogin>
    </user>
  </result>     
</cum>

checksession

Kontrollerar ett sessionid mot databasen och returnerar, om det finns, en användare.

Struktur

<cum>
  <apiKey>%apiKey%</apiKey>
  <command>checksession</command>
  <params>
    <value>%sessionid</value>
  </params>
</cum>

Params

• %sessionid% - Ett sessionid, förmodligen hämtat från en kaka i en klientwebbläsare.

Returvärden

• NO_DATA - Sessionid:t finns inte.
• OK - Sessionen finns, användare följer.

<cum>
  ...
  <result>
    <user>
      <id>%id%</id>
      <username>%username%</username>
      <email>%email</email>
      <displayname>%displayname</displayname>
      <lastlogin>%lastlogin%</lastlogin>
    </user>
  </result>     
</cum>

clearsession

Tar bort en session ur databasen.

Struktur

<cum>
  <apiKey>%apiKey%</apiKey>
  <command>clearsession</command>
  <params>
    <value>%sessionid</value>
  </params>
</cum>

Params

• %sessionid% - Det ID som ska tas bort.

Returvärden

• OK - Sessionen borttagen.

Se även

• CUM
• http://cum.slacker.se/