Getting Started

Introduction

Welcome to the Forum API documentation. Use the sidebar to navigate between different sections. This api was create to administrate the functionality of the real forum, where the users can create, read, update and delete the posts, comments and make threads in each forum. supporting any type of authentication, and the api is open to the public.

Authentication

The api is under a token based authentication, so you need to send a header with the token in every request. this means that you need to get a token, the expiration of the token is 30 minutes, and the token will expire after that time, you can get a new token by sending a pos request to the api on the following endpoint.

POST /api/auth/login

the server wait a body to answer the request with valid credentials, the body must be a json with the following structure:


                    {
                    "username": "username_example",
                    "password": "password_example"
                    }

if your credentials are correct, the server will return a json with the following structure:


                      {
                     "username": "username_example",
                     "message": "user logged sucessfully",
                     "status": "true"
                     "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
                      SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
                     }

if your credentials are not correct, the server will return a json with the following structure:



                      {
                        "username": "null",
                        "message": "incorrect credentials",
                        "status": "null"
                        "jwt": "null"
                        }

before u get a token u can use the api depending of your role and permissions, the roles are:

ADMIN
DEVELOPER
USER
INVITED

Endpoints

Users

The uses endpoint is used to manage users in the system, it can be used to create, update, and delete users. dont forget to pass the token in the header of the request.

GET /api/users

before u pass the token in the header and make the request to that endpoint, the server will return a json with the following structure:


                      {
                      "username": "john_doe_123",
                      "name": "John Doe",
                      "email": "john.doe@example.com",
                      "createdAt": "2024-01-01T12:00:00.000+00:00",
                      "isEnabled": true,
                      "accountNoExpired": true,
                      "accountNoLocked": false,
                      "credentialNoExpired": true,
                      "roles": ["ADMIN", "USER"]
                      }
                
                      {
                      "username": "jane_smith_456",
                      "name": "Jane Smith",
                      "email": "jane.smith@example.com",
                      "createdAt": "2024-02-15T14:30:00.000+00:00",
                      "isEnabled": false,
                      "accountNoExpired": false,
                      "accountNoLocked": true,
                      "credentialNoExpired": false,
                      "roles": ["USER"]
                      }

now if u wanna register to the system u dont need to pass the bearer token in the header, just do the request to the following endpoint

POST /api/auth/sign-up

the server will request a json with the following structure:


                      {
                        "username": "johndoe_123",
                        "password": "John@345", " // Password should have at least 1 uppercase letter, 1 special character, and 3 numbers 
                        "name": "John Doe",
                        "email": "johndoe@example.com",
                        "roleRequest": {
                          "roleListName": ["INVITED"]
                        }
                      }

u can pass a role of user, but the admin and developer not be able in that moment only another admin or developer can add you that role. by default the role is user, but u can select role invited if u want


                      {
                      "username": "janedoe_456",
                      "password": "Jane@678",
                      "name": "Jane Doe",
                      "email": "janedoe@example.com"
                      }

if your credentials are correct, the server will return a json with the following structure:


                      {
                     "username": "username_example",
                     "message": "User created successfully with default role USER.",
                     "status": "true"
                     "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
                      SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
                     }

but if u use an username or email that already exists or if the password is not strong enough, the server will return a json with the following structure:


                    {
                   "username": "null",
                   "message": "User already exists.", // email already exists - Password must contain at least one uppercase letter, two numbers, and one special character
                   "status": "null"
                   "jwt": "null"
                   }

PUT /api/users/{id}/details

to update user, u can select a fill of your preference, bug the role are not editable, just for the admins and developers can add or remove it,if you try to change the fills of another user of the currently logged on the token the system gonna return a json with the following structure:


                   You don't have permission to update this user: u dont have permission to update user details to other users

but if u be admin, developer or the owner of the user logged on the token u can update the user details of the user, the server will return a json with the following structure:


                   User details updated successfully.

DELETE /api/users/deleteAcc/{id}

under the same logic, the admins or developers can delete every user, but if you are a normal user and try to delete another user of the currently logged on the token the system gonna return a json with the following structure:


                   You don't have permission to delete this user: U dont have permission to delete accounts to other users

if u be admin or developer or the owner of the user logged on the token u can delete the user, the server will return a json with the following structure:


                   User deleted successfully.

Forums

The forums on the system. have been created for the objetive to reach a system with a patterns of disscussion, and a system that can be used by the users to create a forum, and to manage the posts of the forum.

we have to options to list the forums, with replies or singles.

GET /api/forums


                      [
                        {
                          "title": "Best coding practices in Java",
                          "description": "Share tips and tricks for writing clean Java code.",
                          "createdAt": "2024-12-20T10:15:30.000+00:00",
                          "ownerId": "1",
                          "messages": [
                            {
                              "content": "Always use meaningful variable names.",
                              "authorUsername": "coder123",
                              "createdAt": "2024-12-20T12:00:00.000+00:00",
                              "replies": [],
                              "parentMessageId": null
                            }
                          ]
                        },
                        {
                          "title": "What is your favorite IDE?",
                          "description": "Discuss the best IDEs for various programming languages.",
                          "createdAt": "2024-12-20T15:45:10.000+00:00",
                          "ownerId": "2",
                          "messages": []
                        }
                      ]

if u want to get a single forum u can use the following endpoint

GET /api/forums/single


                      [
                        {
                          "title": "How to implement a REST API in Java?",
                          "description": "Looking for tips and resources to build a simple REST API using Spring Boot.",
                          "createdAt": "2024-12-13 17:46:12.207",
                          "ownerId": "1"
                        },
                        {
                          "title": "What is the difference between JPA and Hibernate?",
                          "description": "I often hear these terms used interchangeably. Are they the same thing?",
                          "createdAt": "2024-12-13 17:46:12.207",
                          "ownerId": "2"
                        }
                      ]

if u want to create a post is very simple, just use the following endpoint:

POST /api/forums/create-forum

the server will request a json with the following structure:


                      {
                        "title": "How to implement a REST API in Java?",
                        "description": "Looking for tips and resources to build a simple REST API using Spring Boot.",
                      }

after u pass the last json, the server will return a json with the following structure:


                      Forum created successfully.

if u want to update a forum u can use the following endpoint, but the system dont allow update the forums of another users(if u dont have role admin or developer) and the unique fills of the system leave modify are the title and description whatever u want.

PUT /api/forums/update-forum/{id}


                      {
                        "title": "How to implement a REST API in Java?",
                      }

after u update one fill or both fields the system will return a json with the following structure:


                      Forum updated successfully.

if u pass a bad id of the forum, and you dont be the owner of the forum who is currently loged on the token, the system will return a json with the following structure:


                      You don't have permission to update this forum: U dont have permission to update forums to other users

if u want to delete a forum u just need to pass the id of the forum on the endpoint, but the system dont allow delete the forums of another users(if u dont have role admin or developer).

DELETE /api/messages/delete-message/{id}

after u pass the id of the forum, the server will return a json with the following structure:


                      Forum deleted successfully.

if u pass incorrect id the system will return a json with the following structure:


                        You don't have permission to delete this forum: U dont have permission to delete forums to other users

Comments

it is so similar like the forums, if u want to create an message is very simple, just use the following endpoint:

POST /api/messages/create-message


                      [
                        {
                          "content": "content example",
                          "authorUsername": "user_example",
                          "forumId": 1,
                          "replies": [],
                          "parentMessageId": null
                        }
                      ]

for another side, if u want to create a reply is very simple, u dont need to pass the id forum, just the id of the parent message, just use the following endpoint:

POST /api/messages/create-reply

the server will request a json with the following structure:


                      [
                        {
                          "content": "uwu",
                          "authorUsername": "angelito_374",
                          "replies": [],
                          "parentMessageId": 5
                        }
                      ]

if u want to get the messages like a thread is very simple, just use the following endpoint:

GET /api/messages

the server will return a json with the following structure:


                      [
                        {
                          "content": "Welcome to the first forum!",
                          "authorUsername": "user123",
                          "createdAt": "2024-12-01T12:00:00.000+00:00",
                          "replies": [
                            {
                              "content": "Thank you!",
                              "authorUsername": "user456",
                              "createdAt": "2024-12-01T12:30:00.000+00:00",
                              "replies": [
                                {
                                  "content": "Great discussion!",
                                  "authorUsername": "user789",
                                  "createdAt": "2024-12-01T12:45:00.000+00:00",
                                  "replies": [],
                                  "parentMessageId": 2
                                },
                            },
                          },
                          "parentMessageId": null
                        },
                        {
                          "content": "Looking forward to great discussions.",
                          "authorUsername": "user456",
                          "createdAt": "2024-12-02T10:30:00.000+00:00",
                          "replies": [],
                          "parentMessageId": null
                        },
                        {
                          "content": "Enjoy the forum!",
                          "authorUsername": "user789",
                          "createdAt": "2024-12-03T09:15:00.000+00:00",
                          "replies": [],
                          "parentMessageId": null
                        },
                      ]

if u want to update a message is so easy, the system just need the id of the message and the content is the unique fill wich is allowed to update, just use the following endpoint:

PUT /api/messages/upt-message/{id}

the server will request a json with the following structure:


                        comment updated successfully.

if u send a bad id of the message, and you dont be the owner of the message who is currently loged on the token the system gonna return a json with the following structure:


                      You don't have permission to update this message: U dont have permission to update messages to other users

for delete a message is very simple, just use the following endpoint:

DELETE /api//messages/delete-message/{id}

after u pass the id of the message, the server will return a json with the following structure:


                      Message deleted successfully.

if u pass incorrect id the system will return a json with the following structure:


                        You don't have permission to delete this message: U dont have permission to delete messages to other users

Bonus

Admin functionalities

the admins have the possibility to add a new role, and to remove a role from the system, the only thing that the admins can do is to add or remove a role from the system, but the system dont allow to do this, just for the admins and developers can add or remove it and

we have 2 endpoints to add or remove a role from the system, but the system dont allow to do this, just for the admins and developers can add or remove it are be the next:

POST /api/users/{id}/add-role?roleName=INVITED

DELETE /api/users/{id}/remove-role?roleName=INVITED

the server will return a json with the following structure:


                      Role INVITED added successfully to the user.

or the case of the user wanna delete the role from the system, the server will return a json with the following structure:


                        Role INVITED removed successfully from the user.

we have the same functionality with the permissions, to asociate a permission to a role, just use the next endpoint:

POST /api/roles/{id}/add-permission?permissionName=CREATE

DELETE /api/roles/{id}/remove-permission?permissionName=CREATE

the server will return a json with the following structure:


                          Permission CREATE added successfully to the role.

or the case of the user wanna delete the permission from the system, the server will return a json with the following structure:


                            Permission CREATE removed successfully from the role.

the rol functionalities and permissions are deserved only for the admins and developers, in the case of manage or learn more about the roles, we have the following endpoint;

GET /api/roles/with-permissions

the server will return a json with the following structure with yall permissions asociated with the roles:


                              [
                                {
                                  "name": "ADMIN",
                                  "permissions": [
                                    "READ",
                                    "DELETE",
                                    "CREATE",
                                    "UPDATE"
                                  ]
                                },
                                {
                                  "name": "USER",
                                  "permissions": [
                                    "READ"
                                  ]
                                },
                                {
                                  "name": "INVITED",
                                  "permissions": [
                                    "READ"
                                  ]
                                },
                                {
                                  "name": "DEVELOPER",
                                  "permissions": [
                                    "READ",
                                    "CREATE",
                                    "UPDATE"
                                  ]
                                }
                              ]

the documentation is not finished yet, but the api is open to the public, so if u wanna learn more about the api, u can check the git repository for the base code.