API Documentation

REST API Documentation

This could serve as internal documentation. OpenAPI documentation would document external endpoints, with more details

Overview

graph TB
    classDef readyext stroke:#28a745,stroke-width:3px,fill:#d4edda,color:#000
    classDef plannedext stroke:#ffc107,stroke-width:3px,fill:#fff3cd,color:#000
    classDef readyint stroke:#28a745,stroke-width:3px,stroke-dasharray:5 5,fill:#6c757d,color:#fff
    classDef plannedint stroke:#ffc107,stroke-width:3px,stroke-dasharray:5 5,fill:#495057,color:#fff

    subgraph Legend
        L1[🟢 Ready External]:::readyext
        L2[🟡 Planned External]:::plannedext
        L3[🟢 Ready Internal]:::readyint
        L4[🟡 Planned Internal]:::plannedint
    end

    subgraph Auth API
        I[POST /api/auth/register]:::readyext
        J[POST /api/auth/login]:::readyext
    end

    subgraph Users API
        A[GET /api/users/:username]:::readyext
        B[GET /api/users/:id]:::readyext
        C[POST /users/]:::readyint
    end
    
    subgraph Friends API
        D[GET /api/users/friends/]:::readyext
        E[POST /api/users/friends/]:::readyext
        F[PATCH /api/users/friends/:id/nickname]:::readyext
        G[PATCH /api/users/friends/:id/status]:::readyext
        H[DELETE /api/users/friends/:id]:::readyext
    end

Loading

Endpoints

cf OpenAPI for RESTful specs

Warning

Returned id is the authId in DB. users/ prefix should perhaps be changed to users/profiles

API Specifications

Method	Resource	Path	URL Param	Request Param	Request Body	Security (Required role)	Response OK	Response Body	Others Statuses	Status
POST	Auth	/api/auth/register	None	None	username, email, password	Public	200 OK	{}	400, 409	☑️
POST	Auth	/api/auth/login	None	None	username/email, password	Public	200 OK	{}	401	☑️
GET	Profile	/api/users/:id	id	None	None	JWT (User)	200 OK	ProfileDTO	400, 404	👷
GET	Profile	/api/users/username/:username	username	None	None	JWT (User)	200 OK	ProfileDTO	400, 404	☑️
PATCH	Profile	/api/users/avatar/:id	id	None	avatarUrl	JWT (User)	200 OK	ProfileDTO	400, 401, 404	👷
POST	Profile	/users/	None	None	id, username, email	Internal (API Key/Service)	201 Created	ProfileDTO	400, 409	☑️
POST	Friends	/api/users/friends	None	None	id	JWT (User)	201 Created	FriendshipUnifiedDTO	400, 401, 409, 422	☑️
GET	Friends	/api/users/friends/:id	id	None	None	JWT (User)	200 OK	FriendshipUnifiedDTO[]	400, 401, 404	👷
PATCH	Friends	/api/users/friends/:id/status	id	None	status	JWT (User)	200 OK	FriendshipUnifiedDTO	400, 401, 404	👷
PATCH	Friends	/api/users/friends/:id/nickname	id	None	nickname	JWT (User)	200 OK	FriendshipUnifiedDTO	400, 401, 404	👷
DELETE	Friends	/api/users/friends/:id	id	None	None	JWT (User)	200 OK	FriendshipUnifiedDTO	400, 401, 404	👷

ProfileDTO

{
  "authId": 1,
  "username": "toto",
  "avatarUrl": "default.png"
}
  

FriendshipUnifiedDTO

{
  "id": 1,
  "status": "accepted",
  "nickname": "nick",
  "friend": ProfileDTO
}