NCKUPP-Personal backend

Run Application in CLI

Windows

gradlew.bat
gradlew run

Linux/MacOS

./gradlew
./gradlew run

API interpretation

API endpoint: https://pd.potatoez.xyz/api/v0

User Data

 {
    "username":<username: String>,
    "pwd": <pwd: String>
 }

POST /registerregister an account

Response

Success: -status code 200 with JSON object

{
  "token": "<JWT token>"
}

Missing Username: -status code 400 with JSON object

{
  "message": "Missing username"
}

Missing password: -status code 400 with JSON object

{
  "message": "Missing password"
}

Account Exist: -status code 400 with JSON object

{
  "message": "AccountAlreadyExist"
}

JWT token

"exp": 3600s
"user_id": <id>

POST /loginLogin to account

Data

 {
    "username":<username: String>,
    "pwd": <pwd: String>
 }

Success: -status code 200 with JSON object

{
  "token": "<JWT token>"
}

Missing Username: -status code 400 with JSON object

{
  "message": "Missing username"
}

Missing password: -status code 400 with JSON object

{
  "message": "Missing password"
}

User Not Found: -status code 401 with JSON object

{
  "message": "UserNotFound"
}

Wrong password: -status code 401 with JSON object

{
  "message": "WrongPassword"
}

JWT token

"exp": 3600s
"user_id": <id>

Validate User

endpoints below need authorization.

Header

{
  "Authorization": "Bearer <token: String>"
}

Missing JWT token: -status code 401 with JSON Object

{
  "message" : "Token to access HttpHeaders.WWWAuthenticate Bearer realm=potatoez.xyz is either invalid or expired."
}

Missing claim user_id in JWT token: -status code 400 with JSON object

{
  "message": "invalid credentials"
}

user id invalid: -status code 404 with JSON object

{
  "message": "user not found"
}

Event

{
  "id": "<id: String>",
  "title": "<title: String>",
  "start": "<start: String>", 
  "end": "<end: String>",     
  "description": "<description: String>",
  "eventClass": "<eventClass: String>",
  "color": "<color: String>",
  "tags": "<tags: List<String>>"
}

1. time in format ${year}-${month}-${day}T${hour}:${minute}:${second} or ${year}-${month}-${day}

   example: 2024-06-16T15:59:59, 2024-06-16

2. eventClass is class code like 1122_F723300

3. color format in hexadecimal

   example: #F7F7F7

POST /eventsregister event from moodle to db

Data

{
  "ics_url": "<url: String>"
}

Success: -status code 201 with JSON object

{
  "data": "List<Event>"
}

Missing JWT token: -status code 401 with JSON Object

{
  "message" : "Token to access HttpHeaders.WWWAuthenticate Bearer realm=potatoez.xyz is either invalid or expired."
}

Missing claim user_id in JWT token: -status code 400 with JSON object

{
  "message": "invalid credentials"
}

user id invalid: -status code 404 with JSON object

{
  "message": "user not found"
}

Missing url: -status code 400 with JSON object

{
  "message": "Missing ICS URL"
}

GET /eventsget user events

Parameters

"?id=<id>"

if there's no given id

Success: -status code 200 with JSON object

{
  "data": "List<Event>"
}

else

Success: -status code 200 with JSON object

{
  "data": "Event"
}

POST/events/newadding new event to server

Data

{
  "title": "<title: String>",
  "start": "<start: String>",
  "end": "<end: String>",
  "description": "<description: String>",
  "eventClass": "<eventClass: String>",
  "color": "<color: String>",
  "tags": "<tags: List<String>>"
}

Success: -status code 201 with JSON object

{
  "data": "Event"
}

Missing parameters: -status code 400 with JSON Object

{
  "message" : "Missing required parameters"
}

PUT/eventsupdate the event base on given id

Parameters

"?id=<id>"

Data

{
  "id": "<id: String>",
  "title": "<title: String>",
  "start": "<start: String>", 
  "end": "<end: String>",     
  "description": "<description: String>",
  "eventClass": "<eventClass: String>",
  "color": "<color: String>",
  "tags": "<tags: List<String>>"
}

Success: -status code 201 with JSON object

{
  "data": "Event"
}

Missing id: status code 400 with JSON Object

{
  "message" : "Missing ID to update"
}

Missing Data: status code 400 with JSON Object

{
  "message" : "Missing required parameters"
}

Event not found: status code 404 with JSON Object

{
  "message" : "Event not found"
}

Event not modified: status code 304 with JSON Object

{
  "message" : "Event not updated"
}

DELETE/eventsDelete the event base on given id

Parameters

"?id=<id>"

Success: -status code 204 with JSON object

{
  "message": "Event delete success"
}

Missing id: status code 400 with JSON Object

{
  "message" : "Missing ID to update"
}

Q&A

Q: Permission denied when executing ./gradlew in linux

A: chmod +x gradlew

Making Issue for problem shooting or bug report or feature requests is welcome.