API

Server Chat.cz umožňuje přístup přes Rest API na adrese https://chat.cz/api

Struktura požadavku

Požadavek je, příslušnou http metodou (GET, PUT, POST, DELETE), poslán na adresu metody. Pokud jsou požadována dodatečná data, jsou poslány jako hash pole (dictionary) v JSONu.
Na každý požadavek je odpovězeno s HTTP statusem 200 (jiný status znamená chybu přenosu).

Samotná odpověď je JSON hash, který pokaždé obsahuje minimálně tyto dvě položky:

  • status – status operace (používá stejné číselné kódy jako http statusy, tj. 200 – OK, 403 – odmítnutý přístup, 404 – nenalezeno atp.)
  • statusMessage – textový popis statusu (např. OK, chybové hlášení)

V případě, že se vrací data, jsou v samostatné položce.

Metody

Dělí se na dvě skupiny. Anonymní, které nevyžadují autorizaci a autorizované, které ji vyžadují. Některé anonymní metody mohou vrátit data navíc v případě autorizovaného požadavku. Např. seznam místností může vrátit informaci o tom, které místnosti jsou uživatelovy oblíbené.

Anonymní metody

/rooms

GET

Vrátí seznam místností.
Výstup:

rooms – seznam informací o místnosti:
adminUserId – id aktuálního dočasného správce nebo 0
description – popis
id – id místnosti
locked – příznak, jestli a jak je místnost zamčená: “ nebo open – odemčená, logged – pro anonymy, y18 – pro mladší 18 let, all – pro všechny
name – jméno místnosti
permanent – stála (true/false)
userCount – počet lidí v místnosti
web – adresa webovky místnosti

 

/room/<int:roomId>

GET

Vrátí informace o místnosti.
Výstup:

adminUserId – id aktuálního dočasného správce nebo 0
description – popis
id – id místnosti
locked – příznak, jestli a jak je místnost zamčená: “ nebo open – odemčená, logged – pro anonymy, y18 – pro mladší 18 let, all – pro všechny
name – jméno místnosti
permanent – stála (true/false)
userCount – počet lidí v místnosti
web – adresa webovky místnosti

 

 

 /room/<int:roomId>/admins

GET

Vratí seznam stálých správců v místnosti roomId
Výstup:

admins – seznam správců:
id – id uživatele
nick – nick 🙂

 

 

/room/<int:roomId>/users

GET

Vratí seznam uživatelů v místnosti roomId
Výstup:

users – seznam uživatelů v mísnost:
anonym – true/false, jestli je anonymní
id – id uživatele
nick – nick
timeAccess – čas poslední aktivity
timeOnline – čas. odkdy je uživatel online *1)
timeWrite – čas, kdy naposledy psal *1)
sex – pohlaví (m/f)

Poznámka:

  1. zobrazí jen, pokud je uživatel autorizován a ve stejné místnosti

 

 

/user/<int:userId>

GET

Vratí informace o uživateli userId
Výstup:

anonym – true/false, jestli je anonymní
id – id uživatele
nick – nick
online – true/false, jestli je online
timeAccess – čas poslední aktivity
sex – pohlaví (m/f)
rooms – pokud je online, tak seznam místností, v kterých je (id, name)

 

 

/user/<int:userId>/profile

GET

Vratí informace o profilu registrovaného uživatele userId
Výstup:

age – věk uživatele, 0 pokud není vyplněný nebo veřejný
imageUrl – adresa obrázku profilu. Pokud není, tak pole chybí.
karmaLevel – úroveň karmy (0 – nic, 1 – žlutá, 2 – oranžová, 3 – červená)
profileViewCount – počet zobrazení profilu

 

 

Autorizace

Autorizace uživatele se provede pomocí volání dvou metod:

/token

POST

Nastaví a vrátí nový autorizační token pro session

Vstup:

tokenOld – starý token z minulé session
apiKey – klíč přidělený aplikaci

Výstup:

token – nový token, který se musí během 60 vteřin potvrdit v metodě /login

Chyby:

tokenOld data missing, apiKey data missing – chybí vstup
Not found – nebyl nalezen starý záznam pro kombinaci tokenOld a apiKey

 

 /login

PUT

Provede samotné přihlášení a nastavení session

Vstup:

tokenOld – starý token z minulé session
apiKey – klíč přidělený aplikaci

Výstup: –
Chyby:

token data missing, apiKey data missing – chybí vstup
Not found – nebyl nalezen záznam pro kombinaci token a apiKey
New token not validated in 60 seconds – nový token nebyl potvrzen během 60 vteřin