CUM API: Skillnad mellan sidversioner

Från Slackopedia
← Äldre redigering
tempsparar
+clearsession
 
(3 mellanliggande sidversioner av samma användare visas inte)
Rad 1: Rad 1:
'''CUM API''' är alltså [[API|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.
'''CUM API''' är alltså [[API|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 ==
== Saker att komma ihåg ==
Rad 50: Rad 50:


som talar om att lösenordet är felaktigt.
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.
{| class="toccolours" style="border: 5px; margin: 1 auto;"
|-
!style="background:#BFD7FF; font-size:larger;" colspan="4"|Returkodsöversättningstabell
|- style="font-weight: bold;"
|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 ==
== Kommandon ==
Rad 55: Rad 99:
'''%apiKey%''' är rakt igenom din API-nyckel.
'''%apiKey%''' är rakt igenom din API-nyckel.


<h3 style="color: #c00;">auth</h3>
<h3 style="color: #c00; text-decoration: underline;">auth</h3>


Skickar en begäran om autentisering av en användare.
Skickar en begäran om autentisering av en användare.
Rad 80: Rad 124:


* <span style="color: #0a0;">''AUTH_SUCCESS''</span> - Både användarnamn och lösenord är korrekta, användare följer.
* <span style="color: #0a0;">''AUTH_SUCCESS''</span> - 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_PASSWORD'' - Användaren finns men lösenordet för denna användare är felaktigt.
* ''AUTH_INVALID_USERNAME'' - Användaren finns inte.
* ''AUTH_INVALID_USERNAME'' - Användaren finns inte.


<h3 style="color: #c00;">userlist</h3>
<h3 style="color: #c00; text-decoration: underline;">userlist</h3>


Skickar förfrågan om en lista på alla användare och returnerar (oftast) en sådan lista. Eh.
Skickar förfrågan om en lista på alla användare och returnerar (oftast) en sådan lista. Eh.
Rad 100: Rad 158:
==== Returvärden ====
==== Returvärden ====


* <span style="color: #0a0;">''OK''</span> - Sessionen finns, användarlista följer.
* <span style="color: #0a0;">''OK''</span> - 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>


<h3 style="color: #c00;">checksession</h3>
<h3 style="color: #c00; text-decoration: underline;">checksession</h3>


Kontrollerar ett sessionid mot databasen och returnerar, om det finns, en användare.
Kontrollerar ett sessionid mot databasen och returnerar, om det finns, en användare.
Rad 124: Rad 202:
* ''NO_DATA'' - Sessionid:t finns inte.
* ''NO_DATA'' - Sessionid:t finns inte.
* <span style="color: #0a0;">''OK''</span> - Sessionen finns, användare följer.
* <span style="color: #0a0;">''OK''</span> - 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>
<h3 style="color: #c00; text-decoration: underline;">clearsession</h3>
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 ====
* <span style="color: #0a0;">''OK''</span> - Sessionen borttagen.


== Se även ==
== Se även ==
Rad 131: Rad 243:


[[Kategori:IT]]
[[Kategori:IT]]
[[Kategori:Jag är helt seriös nu, och jag vill inte att ni larvar er]]

Nuvarande version från 10 april 2006 kl. 09.07

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

Hämtad från ”https://wiki.slacker.se/index.php?title=CUM_API&oldid=9887”