API Design

[ziad-ashraf7]

TODO

Creating a Doc that contains:

• API endpoints & routs
• Endpoint contain (method, req, res)
• Scheme of the request
• Scheme of the response

[ziad-ashraf7]

Endpoints

Feed

GET api/feed -> getting all the threads in the system

Res

list of all the threads in the DB

[
	{
		"Id": 1,
		"QuestionContent": "This is a new question",
		"AnswerContent": "And this is a new Answer",
		"Status": "PRIVATE, PUBLIC, Closed, PRIVATEQUESTION",
		"isAnonymous": true,
		"CreatedAt": "NOW",
		/* if the user is not anonymous */
		"Asker": {
		  "Id": 12,
		  "Username": "ziad",
		  "AvatarPath": "..."
		}
		"Asked":{
			"Id": 7,
			"Username": "Mahmoud",
			"AvatarPath": "..."
		}
		"ThreadLikeCount": 5,
		
	}
]

Auth

POST api/auth/login -> Login in to the System

Req

{
	"email": "ziad@gmail.com" ,
	"password": "ziad123"
}

Res

Status: 200 -> User logged in
returning the user's object response

{

	"id":  1,
	
	"name":  "Ziad Ashraf",
	
	"username": "ziad777" ,
	
	"avatar_path": "image/path.jpeg" ,
	
	"bio": "Software engineer @Google" ,
	
}

---

POST api/auth/signup -> Sign up to the System

Req

{
	"name": "Ziad Ashraf" ,
	
	"username":  "ziad777" ,
	
	"email": "ziad@gmail.com" ,
	
	"password": "ziad123" ,
	
	"bio": "Software engineer @Google" 
}

Res

Status: 201 -> User Created

returning the token and the user response object

{
	"id": 1,
	
	"name":  "Ziad Ashraf",
	
	"username": "ziad77" ,
	
	"email": "ziad@gmail.com" ,
	
	"created_at":  "2025-07-31T19:39:00Z"
}

---

POST api/auth/logout -> Log out from the System

Res

Status: 200 -> User Logged out

{
	"message": "User logged out seccessfully!"
}

POST /api/auth/forgot-password

---

User

GET api/users/{uid} -> getting the profile for the User with id = uid

Res

{
	"id" : 1,
	
	"name": "Ziad Ashraf" ,
	
	"username":  "ziad777" ,
	
	"email": "ziad@gmail.com" ,
	
	"avatar_path": "image/path.jpeg" ,
	
	"bio": "Software engineer @Google",
	
	"created_at":  "2025-07-31T19:39:00Z",
	
	"last_seen": "2025-07-31T19:39:00Z"
}

---

PATCH api/users/settings/profile -> Updating the profile for the User with id = uid

Req

{
	"name": "Ziad Ashraf" ,
	
	"username":  "ziad777" ,
	
	"email": "ziad@gmail.com" ,
	
	"avatar_path": "image/path.jpeg" ,
	
	"bio": "Software engineer @Google",	
}

Res

Status 200 -> Profile Updated

returning the User's object response after updating

{
	"name": "Ziad Ashraf" ,
	
	"username":  "ziad777" ,
	
	"email": "ziad@gmail.com" ,
	
	"avatar_path": "image/path.jpeg" ,
	
	"bio": "Software engineer @Google",	
}

---

GET api/users/{uid}/Followers -> getting the followers list for User with id = uid

GET api/users/{uid}/Followings -> getting the following list for User with id = uid

GET api/users/{uid}/threads -> getting the threads list for User with id = uid

DELETE /api/users/{id} (delete account)

GET /api/search/users?q={query} (Search by username)

Threads

POST api/threads/ -> Ask a question
GET api/threads/{id} -> Getting the Thread with id = id
PUT api/threads/{id}/answer -> Add an Answer on the thread with id = id

POST api/threads/{id}/likes -> Add a Like to the thread with id = id
GET api/threads/{id}/likes -> get all the Likes to the thread with id = id
DELETE api/threads/{id}/likes -> Unlike to the thread with id = id

POST api/threads/{id}/comments -> Add a comment to the thread with id = id
GET api/threads/{id}/comments -> get all the comment to the thread with id = id
DELETE api/threads/{id}/comments -> remove the comment to the thread with id = id

DELETE /api/threads/{id} (delete thread)

PATCH /api/threads/{id} (edit thread)

Comment

GET api/comment/{id}/likes -> get all the likes for a Comment with id = id
POST api/comment/{id}/likes -> add a like for a Comment with id = id
DELETE api/comment/{id}/likes -> delete a like for a Comment with id = id

Follow

POST api/follow -> follow a user

{
	"follower_id": 1,
	"followed_id": 2
}

DELETE api/follow -> unfollow a user

Notifications

GET /api/notifications -> getting the users notifications

Res

[
    {
        "id": 1,
        "type": "like",
        "message": "user1 liked your thread",
        "is_read": false,
        "created_at": "2025-07-31T19:42:00Z",
        "resource_id": 1,
    }
]

PUT /api/notifications/{id}/read -> Mark notification with id = id as read

{
	"message": "noti has been read",
}

PUT /api/notifications/read Mark all notifications as read

GET /api/notifications/{category}

Response

  "category": "QUESTION_LIKE",
  "notifications": [
    {
      "id": 1,
      "type": "QUESTION_LIKE",
      "message": "user1 liked your question",
      "isRead": false,
      "createdAt": "2025-07-31T19:42:00Z",
      "resourceId": 1,
      "actor": {
        "id": 12,
        "username": "ziad",
        "avatarPath": "..."
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalCount": 45,
    "hasNext": true,
    "hasPrevious": false
  }
}```