CUM API: Skillnad mellan sidversioner

Från Slackopedia
← Äldre redigeringNyare redigering →
tempsparar
ok
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 101: Rad 159:


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


== Se även ==
== Se även ==

Versionen från 10 april 2006 kl. 08.54

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.

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 - Sessionen finns, 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>

Se även

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