-
Notifications
You must be signed in to change notification settings - Fork 0
eap
In today's dynamic social media landscape, there's a growing need for a user-friendly platform, especially among students and academics seeking reliable information and effective communication tools. With this goal in mind, our network aims to redefine the social networking experience.
This document serves as an OpenAPI format guideline in order to present to end users the use cases available within our public API. Some Modules are defined but have few or no requests because they are not implemented in the vertical prototype.
Modules | Description |
---|---|
M01: Authentication | Web resources associated with user authentication and registration, with features such as login/logout and registration. |
M02: Feed | Web resources used to show the home page, where posts are displayed in a public or personalized feed for both users and visitors, as well as links to other pages. |
M03: User Administration | Web resources that allows the admins to create, edit, ban and delete users. |
M04: Static Pages | Web resources associated with FAQ, Contacts, About Us or the main features of the system. |
M05: Users | Web resources associated with getting information about a profile or editing it, as well as adding and removing other users as friends. |
M06: Search | Web resources associated with searching for a user, group or post. |
M07: Posts | Web resources that allows the user to create, edit, delete and see the posts as well as their comments and reactions. |
M08: Groups | Web resources that allows the user to see, create, edit and delete groups, as well as adding users to groups. |
M09: Notifications | Web resources that are used to send and receive notifications to users about groups, tags, reactions, comments and friends. |
Identifier | Name | Description |
---|---|---|
GST | Guest | An unauthenticated user. |
USR | User | An authenticated user. |
ATH | Author | The owner of a post, comment. |
GRO | Group Owner | The owner of a group |
ADM | Administrator | Platform administrator. |
openapi: 3.0.0
info:
version: '0.1'
title: 'Gamma Public API'
description: 'Web Resources Specification (A7) for Gamma'
servers:
- url: https://lbaw2391.lbaw.fe.up.pt
description: Production server
externalDocs:
description: Find more info here.
url: https://git.fe.up.pt/lbaw/lbaw2324/lbaw2391/-/wikis/eap
tags:
- name: 'M01: Authentication'
- name: 'M02: Feed'
- name: 'M03: User Administration'
- name: 'M04: Static Pages'
- name: 'M05: Users'
- name: 'M06: Search'
- name: 'M07: Posts'
- name: 'M08: Groups'
- name: 'M09: Notifications'
paths:
/login:
get:
operationId: R101
summary: 'R101: Login Form'
description: 'Provide login form. Access: VST'
tags:
- 'M01: Authentication'
responses:
'200':
description: 'Get login form view.'
post:
operationId: R102
summary: 'R102: Login Action'
description: 'Processes the login form submission. Access: VST'
tags:
- 'M01: Authentication'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
properties:
email:
type: string
format: email
password:
type: string
format: password
required:
- email
- password
responses:
'302':
description: 'Redirect after processing the new user information.'
headers:
Location:
schema:
type: string
examples:
'302 Success':
description: 'OK. Redirect to homepage.'
value: '/home'
'302 Failure':
description: 'NOT OK. Redirect again to login form.'
value: '/login'
Set-Cookie:
cookie-name:
type: string
cookie-value:
type: string
Expires:
type: string
/logout:
post:
operationId: R103
summary: 'R103: Logout Action'
description: 'Logout the current logged user. Access: USR'
tags:
- 'M01: Authentication'
responses:
'302':
description: 'Redirect after processing logout.'
headers:
Location:
schema:
type: string
examples:
'302 Success':
description: 'OK. Redirect to public feed.'
value: '/'
/register:
get:
operationId: R104
summary: 'R104: Register Form'
description: 'Register a new user. Access: VST'
tags:
- 'M01: Authentication'
responses:
'200':
description: 'Sign-up is ready'
post:
operationId: R105
summary: 'R105: Register Action'
description: 'Processes a new registration request. Access: VST'
tags:
- 'M01: Authentication'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: text
format: binary
username:
type: string
email:
type: string
academic_status:
type: string
display_name:
type: string
is_private:
type: boolean
required:
- email
- password
- username
responses:
'302':
description: 'Redirect after the register'
headers:
Location:
schema:
type: string
examples:
'302 Success':
description: 'The user was registered with success. Redirect to his personal page'
value: '/users/{id}'
'302 Failure':
description: 'The user was not registered with success. Redirect to the login form'
value: '/login'
/api/sendResetPassword:
post:
operationId: R106
summary: 'R106: Send Email Action'
description: 'Sends an email with a certain type. Access: VST'
tags:
- 'M01: Authentication'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
email:
type: string
required:
- email
responses:
'200':
description: 'OK. An email with a password link was sent.'
/resetPassword/{token}:
get:
operationId: R107
summary: 'R107: Register Form'
description: 'Get the view for the form to reset the password. Access: VST'
tags:
- 'M01: Authentication'
parameters:
- in: path
name: token
schema:
type: string
required: true
responses:
'200':
description: 'Reset the password form returned'
post:
operationId: R108
summary: 'R108: Reset Password'
description: 'Sends a reset password request. Access: VST'
tags:
- 'M01: Authentication'
parameters:
- in: path
name: token
schema:
type: string
required: true
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
new_password:
type: string
confirm_new_password:
type: string
required:
- new_password
- confirm_new_password
responses:
'200':
description: 'OK. You received a token on your email.'
'404':
description: 'Error. Email doesnt exist.'
/api/sendVerifyEmail:
post:
operationId: R109
summary: 'R109: Send Email Action'
description: 'Sends an email with a certain type. Access: VST'
tags:
- 'M01: Authentication'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
email:
type: string
required:
- email
responses:
'200':
description: 'OK. You received a token on your email.'
'404':
description: 'Error. Email doesnt exist.'
/verifyEmail/{token}:
get:
operationId: R110
summary: 'R110: Verify Email Form'
description: 'Get the view for the form to reset the password. Access: VST'
tags:
- 'M01: Authentication'
parameters:
- in: path
name: token
schema:
type: string
required: true
responses:
'200':
description: 'Reset the verify email form returned'
post:
operationId: R111
summary: 'R111: Send Verify Email Request'
description: 'Sends a verify email request to the server'
parameters:
- in: path
name: token
schema:
type: string
required: true
tags:
- 'M01: Authentication'
responses:
'200':
description: 'OK. Email verified.'
/feed/:
get:
operationId: R201
summary: 'R201: Provide popular feed'
description: 'Get the page with the feed. Access: VST'
tags:
- 'M02: Feed'
responses:
'200':
description: 'OK. Show popular feed UI'
/feed/personal:
get:
operationId: R202
summary: 'R202: Provide personalized feed'
description: 'Get the page with the feed. Access: USR'
tags:
- 'M02: Feed'
responses:
'200':
description: 'OK. Show personalized feed UI'
/admin/user:
get:
operationId: R301
summary: 'R301: Show administration page for actions on users'
description: 'Shows an administration page where the admin can search for users and perform actions on them. Access: ADM'
tags:
- 'M03: User Administration'
responses:
'200':
description: 'OK. Show User Administration Page'
/admin/user/create:
get:
operationId: R302
summary: 'R302: Shows page to create user'
description: 'Shows the view for the page where an admin can create a new user. Access: ADM'
tags:
- 'M03: User Administration'
responses:
'200':
description: 'OK. Show create user page by admin'
/users/{username}/block:
post:
operationId: R303
summary: 'R303: Blocks an user.'
description: 'Performs the ban of an user of the application. Access: ADM'
tags:
- 'M03: User Administration'
parameters:
- in: path
name: username
schema:
type: string
required: true
responses:
'200':
description: 'Success'
'403':
description: 'Forbidden. Requester is not an admin'
'422':
description: 'Unprocessable Entity. Username does not exist'
/users/{username}/unblock:
post:
operationId: R304
summary: 'R304: Unblocks user.'
description: 'Allows an admin to unblock a valid user. Access: ADM'
tags:
- 'M03: User Administration'
parameters:
- in: path
name: username
schema:
type: string
required: true
responses:
'200':
description: 'Success'
'403':
description: 'Forbidden. Requester is not an admin'
'422':
description: 'Unprocessable Entity. Username does not exist'
/api/admin/search/users/{query}:
get:
operationId: R305
summary: 'R305: Previews the users search result to use for AJAX in the admin page.'
description: 'Allows the search for users. Access: ADM'
parameters:
- in: path
name: query
description: String to use for full-text search
schema:
type: string
required: false
tags:
- 'M03: User Administration'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
image:
type: string
username:
type: string
e-mail:
type: string
academic_status:
type: string
display_name:
type: string
is_private:
type: boolean
example:
- id: 1
image: url/of/the/image.jpg
username: john_doe
e-mail: johndoe@trigger.com
academic_status: Student
display_name: John Doe
is_private: False
- id: 28
image: url/of/the/image2.jpg
username: carlosbarbossa
e-mail: carlosbarbossa@carlosbarbossa.com
academic_status: Student
display_name: Carlos Barbossa
is_private: False
/users/{username}:
get:
operationId: R501
summary: 'R501: Profile Action.'
description: 'Get the page view for a user profile. Access: VST, USR'
tags:
- 'M05: Users'
responses:
'200':
description: 'OK. Show User Profile'
'403':
description: 'Forbidden. User doesnt have access to this profile.'
parameters:
- in: path
name: username
schema:
type: string
required: true
delete:
operationId: R502
summary: 'R502: Deletes an user'
description: 'Allows an authenticated user or admin to delete himself or another user (if admin). Access: USR, ADM'
tags:
- 'M05: Users'
parameters:
- in: path
name: username
schema:
type: string
required: true
responses:
'200':
description: Success
'422':
description: Failure. If user not found with username
'403':
description: Action forbidden
/users/{username}/edit:
get:
operationId: R503
summary: 'R503: Edit Profile Form'
description: 'Provide edit profile form. Access: USR'
tags:
- 'M05: Users'
responses:
'200':
description: 'Get the view of the edit post form'
'403':
description: 'Forbidden. User doesnt own this profile.'
parameters:
- in: path
name: username
schema:
type: string
required: true
put:
operationId: R504
summary: 'R504: Edit Profile Action'
description: 'Processes the edit profile form submission. Access: USR'
tags:
- 'M05: Users'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: text
format: binary
username:
type: string
academic_status:
type: string
display_name:
type: string
is_private:
type: boolean
password:
type: string
responses:
'302':
description: 'Redirect after processing the new user information.'
headers:
Location:
schema:
type: string
examples:
'302 Success':
description: 'OK. Redirect to profile page.'
value: '/users/{id}'
'302 Failure':
description: 'NOT OK. Redirect again to edit profile form.'
value: '/users/{id}/edit'
/api/users/username/{username}:
get:
operationId: R505
summary: 'R505: Retrieve user by username'
description: 'Get the user information by username. Access: VST, USR'
tags:
- 'M05: Users'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
username:
type: string
email:
type: string
image:
type: string
academic_status:
type: string
display_name:
type: string
is_private:
type: boolean
role:
type: integer
tsvectors:
type: string
parameters:
- in: path
name: username
description: Username of the user
schema:
type: string
required: true
/api/users/email/{email}:
get:
operationId: R506
summary: 'R506: Retrieve user by email'
description: 'Get the user information by email. Access: VST, USR'
tags:
- 'M05: Users'
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
username:
type: string
email:
type: string
image:
type: string
academic_status:
type: string
display_name:
type: string
is_private:
type: boolean
role:
type: integer
tsvectors:
type: string
parameters:
- in: path
name: email
description: Email of the user
schema:
type: string
required: true
/post:
post:
operationId: R701
summary: 'R701: Create Post Action'
description: 'Processes the create post form submission. Access: USR'
tags:
- 'M07: Posts'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
attachment:
type: text
format: binary
title:
type: string
content:
type: string
is_private:
type: boolean
group:
type: string
required:
- title
- content
- is_private
responses:
'302':
description: 'Redirect after processing the new post information.'
headers:
Location:
schema:
type: string
examples:
'302 Success':
description: 'OK. Redirect to post page.'
value: '/post/{id}'
'302 Failure':
description: 'NOT OK. Redirect again to create post form.'
value: '/post'
get:
operationId: R702
summary: 'R702: Get post page creation'
description: 'Provide post creation page. Access: USR'
tags:
- 'M07: Posts'
responses:
'200':
description: 'OK. Show Post'
'403':
description: 'Forbidden. User is not logged in.'
/api/post/{id}:
get:
operationId: R703
summary: 'R703: Get post from id as JSON'
description: 'Get post from id. Access: ATH'
tags:
- 'M07: Posts'
parameters:
- in: path
name: id
description: Id of the post
schema:
type: string
required: true
responses:
'200':
description: 'OK.'
content:
application/json:
schema:
type: object
properties:
author:
type: string
title:
type: string
content:
type: string
date:
type: string
attachment:
type: string
group:
type: string
example:
author: killme
title: MongoDB vs ScyllaDB
content: Can you provide with an explanation as to which one of those is better?
date: 2023-10-29
attachment: null
group: null
'403':
description: 'Forbidden. User doesnt own this post.'
/post/{id}:
get:
operationId: R704
summary: 'R704: Get post page'
description: 'Provide post page. Access: USR, VST, ADM. Visitor can only see public posts while Authenticated User can see private posts from himself, friends or groups. Administrator can see all posts.'
tags:
- 'M07: Posts'
parameters:
- in: path
name: id
description: Id of the post
schema:
type: string
required: true
responses:
'200':
description: 'OK. Show Post'
'403':
description: 'Forbidden. User not allowed to see post.'
delete:
operationId: R705
summary: 'R705: Delete post'
description: 'Processes the delete post request. Access: ATH, ADM'
tags:
- 'M07: Posts'
parameters:
- in: path
name: id
description: Id of the user
schema:
type: string
required: true
responses:
'200':
description: 'OK. Post deleted.'
'403':
description: 'Forbidden. User doesnt own this post.'
/post/{id}/edit:
get:
operationId: R706
summary: 'R706: Edit Profile Form'
description: 'Show edit post form. Access: ATH'
tags:
- 'M07: Posts'
parameters:
- in: path
name: id
description: Id of the post
schema:
type: string
required: true
responses:
'200':
description: 'OK. Show Post'
'403':
description: 'Forbidden. User doesnt own this post.'
put:
operationId: R707
summary: 'R707: Edit Post Action'
description: 'Processes the edit post form submission. Access: ATH'
tags:
- 'M07: Posts'
parameters:
- in: path
name: id
description: Id of the post
schema:
type: string
required: false
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
attachment:
type: text
format: binary
title:
type: string
content:
type: string
is_private:
type: boolean
responses:
'302':
description: 'Redirect to post page (post/{id})'
headers:
Location:
schema:
type: string
examples:
302Success:
description: 'Successful edit. Redirect to post page.'
value: '/post/{id}'
302Failure:
description: 'Failed edit. Fix the errors and try again.'
value: '/post/{id}/edit'
'403':
description: 'Forbidden'
/search/{query}:
get:
operationId: R601
summary: 'R601: Search Action'
description: 'Allows the search for users, posts and groups. Access: VST, USR'
tags:
- 'M06: Search'
parameters:
- in: path
name: query
description: Search query
schema:
type: string
required: false
responses:
'200':
description: 'OK. Show Search UI'
/api/search/users/{query}:
get:
operationId: R602
summary: 'R602: Previews the users search result to use for AJAX'
description: 'Allows the search for users. Access: VST, USR'
tags:
- 'M06: Search'
parameters:
- in: path
name: query
description: String to use for full-text search
schema:
type: string
required: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
image:
type: string
username:
type: string
e-mail:
type: string
academic_status:
type: string
display_name:
type: string
is_private:
type: boolean
example:
- id: 1
image: url/of/the/image.jpg
username: john_doe
e-mail: johndoe@trigger.com
academic_status: Student
display_name: John Doe
is_private: False
- id: 28
image: url/of/the/image2.jpg
username: carlosbarbossa
e-mail: carlosbarbossa@carlosbarbossa.com
academic_status: Student
display_name: Carlos Barbossa
is_private: False
/api/search/posts/{query}:
get:
operationId: R603
summary: 'R603: Posts Search Action'
description: 'Allows the search for posts. Access: VST, USR'
tags:
- 'M06: Search'
parameters:
- in: path
name: query
description: String to use for full-text search
schema:
type: string
required: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
author:
type: integer
title:
type: string
content:
type: string
attachement:
type: string
group_id:
type: integer
is_private:
type: boolean
/api/search/groups/{query}:
get:
operationId: R604
summary: 'R604: Previews the groups search result to use for AJAX'
description: 'Allows the search for groups. Access: VST, USR'
tags:
- 'M06: Search'
parameters:
- in: path
name: query
description: String to use for full-text search
schema:
type: string
required: false
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
is_private:
type: boolean
example:
- id: 1
name: Prolog Enthusiasts
description: A community for discussing Prolog programming language and related topics
is_private: False
- id: 2
name: Tech Enthusiasts
description: A group dedicated to discussing the latest technology trends and innovations
is_private: True
It is possible to find the yaml file for the OpenApi specification here
This artifact pretends to represent the initial stage of engagement with the development of the application. It encompasses the incorporation of certain user stories into the implementation process. The user stories that were implemented in this vertical prototype were mainly those with high priority.
User Story reference | Name | Priority | Description |
---|---|---|---|
US01 | View Public Timeline | High | As an User, I want to be able to view the public posts of all users so that I don't need to register/login. |
US02 | View Public Profiles | High | As an User, I want to be able to view the profile of all public users so that I don't need to register/login. |
US03 | Search for Public Profiles | High | As an User, I want to be able to search for public users so that I don't need to register/login. |
US04 | Exact Match Search | High | As a User I want be able to specify to the search engine that I want to see only results with specific words that I can specify during the search so that the search becomes more efficient. |
US05 | Full Text Search | High | As a User I want be able to specify to the search engine certain text terms and I want to find the result that contain pieces of those texts so that the search becomes more efficient. |
US14 | Login | High | As a Guest, I want to be able to login to my account so that I can post. |
US15 | Register | High | As a Guest, I want to be able to register a new account so that I can empower myself to have the capabilities of an authenticated user. |
US16 | Logout | High | As an Authenticated User, I want to be able to logout from my account so that I can delete my session. |
US17 | Search | High | As an Authenticated User, I want to be able to search for users, posts and groups, private or public so that I can enter in the respective pages. |
US18 | View Profile | High | As an Authenticated User, I want to be able to view my profile as well as other users' public profiles so that I can send friendship invites. |
US22 | Create Post | High | As an Authenticated User I want to be able to create a post with a text and other relevant attachments so that I can express myself better. |
US23 | View Personalized Timeline | High | As an Authenticated User, I want to be able to view the posts of the users I'm friends with and of the groups I belong. |
US27 | Edit Profile | High | As an Authenticated User, I want to be able to edit my profile so that I can edit it. |
US49 | Edit Post | High | As a Post Author, I want to edit my post, so that I can ensure the correctness of the post. |
US50 | Delete Post | High | As a Post Author, I want to delete my post, so that I can remove my content from the website. |
US57 | Administer Account | High | As a Admin, I want an account with higher privileges, so that i can manage the website. |
US58 | Manager User Accounts | High | As a Admin, I want to search user accounts, so i can easily manage the accounts in the website. |
US59 | Delete User Accounts | High | As a Admin, I want to be able to delete users accounts, to manage the website. |
US60 | Create Users Accounts | High | As a Admin, I want to be able to create users accounts, to manage the website. |
US61 | Edit Users Accounts | High | As a Admin, I want to be able to edit users accounts, that is, to delete their posts, comments or reactions, to manage the website. |
M01: Authentication
Web Resource Reference | URL |
---|---|
R101: Login Form | GET /login |
R102: Login Action | POST /login |
R103: Logout Action | GET /logout |
R104: Register Form | GET /register |
R105: Register Action | POST /register |
Module M02: Feed
Web Resource Reference | URL |
---|---|
R201: Popular feed | GET /feed |
R202: Personalized feed | GET /feed/personal |
Module M03: User Administration
Web Resource Reference | URL |
---|---|
R301: Show administration page for actions on users | GET /admin/user |
R302: Show pages to create user. | GET /feed/personal |
R303: Blocks a user | POST /users/{username}/block |
R304: Unblocks a user | POST /users/{username}/unblock |
R305: Search for users as an admin | GET /api/admin/search/users |
Module M05: Users
Web Resource Reference | URL |
---|---|
R501: Profile Action | GET /users/{username} |
R502: Deletes an user | DELETE /users/{username} |
R503: Edit Profile Form | GET /users/{username}/edit |
R504: Edit Profile Action | PUT /users/{username}/edit |
R505: Retrieve a user by username | GET /api/users/username/{username} |
R506: Retrieve a user by email | GET /api/users/email/{email} |
Module M06: Search
Web Resource Reference | URL |
---|---|
R601: Search Action | GET /search/{query} |
R602: Retrieve a preview of the users | GET /api/search/users |
R603: Retrieve a prefiew of the posts | GET /api/search/posts |
R604: Retrieve a preview of the groups | GET /api/search/groups |
Module M07: Posts
Web Resource Reference | URL |
---|---|
R701: Create Post Action | POST /post/ |
R702: Show page form creation | GET /post/ |
R703: Retrieve post | GET /api/post/{id} |
R704: Show post page | GET /post/{id} |
R705: Delete post | DELETE /post/{id} |
R706: Show Edit Post Page Form | GET /post/{id}/edit |
R707: Edit Post Action | PUT /post/{id}/edit |
Production version available at: https://lbaw2391.lbaw.fe.up.pt/
Source code available at: https://git.fe.up.pt/lbaw/lbaw2324/lbaw2391
User with the admin role:
e-mail: admin@example.com
password: admin
User without privileges:
e-mail: johndoe@example.com
password: hello
Changes made to the first submission:
- Added A7 (20th October 2023)
- Added implemented user stories and information about prototype deployed website link and source code (17th November 2023)
- Added implemented web resources (19th November 2023)
- Switched order of resource identifiers on the User Module to be consistent with the yaml file inside the gitlab repository. (20th November 2023)
- Updated YAML (20th November 2023)
GROUP2391, 20/11/2023
- Davide Teixeira, up202109860@up.pt (editor)
- João Fernandes, up202108867@up.pt
- Pedro Oliveira, up202108669@up.pt
- Tomás Palma, up202108880@up.pt