📚 ShutAppChat API Reference

Documentazione completa degli endpoint REST e WebSocket. Tutte le richieste autenticate richiedono header Authorization: Bearer <jwt_token>

Base URL: https://shutappchat.fabiodirauso.it/api/v2/

Autenticazione

POST/auth/register

Registra un nuovo utente

ParametroTipoObbligatorioDescrizione
usernamestringSì3-20 caratteri
passwordstringSìMinimo 6 caratteri
nicknamestringSìNome visualizzato
POST /auth/register
{"username":"mario","password":"securepass","nickname":"Mario Rossi"}

POST/auth/login

Login utente esistente

ParametroTipoObbligatorioDescrizione
usernamestringSìUsername
passwordstringSìPassword
Response: {"token":"eyJhbGc...","user":{"id":1,"username":"mario"}}

POST/auth/refresh

Rinnova il token JWT (richiede token valido)

Header: Authorization: Bearer <token>

Utenti

GET/users?q={query}

Cerca utenti per username

ParametroTipoDescrizione
qstringQuery di ricerca (minimo 2 caratteri)
GET /users?q=mario
Response: [{"id":1,"username":"mario","nickname":"Mario Rossi","profilePicture":null}]

GET/users/{username}

Ottieni profilo pubblico di un utente

GET /users/mario

Profilo

GET/profile/me

Ottieni il proprio profilo completo

Header: Authorization: Bearer <token>

POST/profile/update_user_info

Aggiorna nickname e stato

ParametroTipoDescrizione
nicknamestringNuovo nickname
statusstringStato (es. "Disponibile")

POST/profile/update_profile_picture

Aggiorna immagine profilo

Content-Type: multipart/form-data
Field: profile_picture (file immagine)

Contatti

GET/contacts

Lista di tutti i contatti accettati

GET/contacts/requests

Richieste di contatto in sospeso

POST/contacts/request

Invia richiesta di amicizia

ParametroTipoDescrizione
recipient_usernamestringUsername destinatario

POST/contacts/respond

Rispondi a una richiesta (accetta/rifiuta)

ParametroTipoValori
request_idintID richiesta
actionstring"accept" o "reject"

DELETE/contacts/{username}

Rimuovi un contatto

Messaggi

POST/messages

Invia un messaggio (1-a-1 o gruppo)

ParametroTipoDescrizione
recipient_idintID utente destinatario (per chat 1-a-1)
group_idintID gruppo (per messaggi di gruppo)
contentstringTesto del messaggio
media_idintID media allegato (opzionale)

GET/pendings

Ottieni messaggi pendenti (non consegnati durante offline)

Media

POST/media

Crea una sessione di upload media

ParametroTipoDescrizione
filenamestringNome file originale
file_sizeintDimensione in byte
media_typestring"image", "video", "document"
Response: {"media_id":123,"upload_token":"abc..."}

PUT/media/data?id={media_id}

Upload del file binario

Header: X-Upload-Token: <upload_token>
Body: binary file data

Gruppi

GET/groups

Lista gruppi di cui fai parte

POST/groups/create

Crea un nuovo gruppo

ParametroTipoDescrizione
group_namestringNome gruppo
descriptionstringDescrizione
modestring"OPEN" (tutti postano) / "RESTRICTED" (solo admin)

GET/groups/{groupId}/info

Informazioni dettagliate gruppo

GET/groups/{groupId}/members

Lista membri del gruppo

POST/groups/{groupId}/members/add

Aggiungi membri (solo admin)

ParametroTipoDescrizione
user_idsint[]Array di ID utenti

DELETE/groups/{groupId}/members/{userId}

Rimuovi membro (solo admin)

PUT/groups/{groupId}/members/{userId}/role

Cambia ruolo membro

ParametroTipoValori
rolestring"ADMIN" o "MEMBER"

PUT/groups/{groupId}/settings

Modifica impostazioni gruppo (solo admin)

ParametroTipoDescrizione
group_namestringNuovo nome
descriptionstringNuova descrizione
modestring"OPEN" o "RESTRICTED"

DELETE/groups/{groupId}

Elimina gruppo (solo admin creatore)

WebSocket

URL: wss://shutappchat.fabiodirauso.it/ws

Connessione

wss://shutappchat.fabiodirauso.it/ws?token=<jwt_token>

Messaggi Client Server

TipoPayloadDescrizione
message{"recipient_id":1,"content":"..."}Messaggio diretto
group_message{"group_id":5,"content":"..."}Messaggio gruppo
typing{"recipient_id":1,"isTyping":true}Stato digitazione
read_receipt{"message_id":123}Conferma lettura

Messaggi Server Client

TipoDescrizione
messageNuovo messaggio ricevuto
group_messageMessaggio gruppo ricevuto
systemNotifica di sistema
group_updatedGruppo modificato
session_expiredToken scaduto, riconnettiti
typingUtente sta digitando

Rate Limiting

EndpointLimiteFinestra
/auth/*10 richieste1 minuto
/api/v2/* (generale)100 richieste1 minuto
/media/*20 richieste1 minuto
WebSocket messages50 messaggi1 minuto

Headers di risposta

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1634567890

Codici di Errore

CodiceSignificato
400Bad Request - Parametri mancanti/non validi
401Unauthorized - Token mancante/non valido
403Forbidden - Permessi insufficienti
404Not Found - Risorsa non trovata
429Too Many Requests - Rate limit superato
500Internal Server Error - Errore server