API Specification Doc

(Application Name)

Version Date Author Description

1.0 19-Aug-2023 Jothi Prakash V Initial draft

1.1 19-Aug-2023 Jothi Prakash V Added Course Management Service

1.1 20-Aug-2023 Jothi Prakash V  Added Module, Enrollemnt,

Authentication & Authorization
Services.
 Added Payment and Billing
Endpoints.
Index
Table of Contents
API Documentation.................................................................................................................3
1. User Management Service.................................................................................................3
1.1. List of Endpoints.................................................................................................................3
1.2. Register a new user in the system......................................................................................4
1.3. Fetch User Profile...............................................................................................................5
1.4. Retrieve Users by Role.......................................................................................................6
1.5. Assign Role to User............................................................................................................7
1.6. Revoke Role from User.......................................................................................................8
1.7. Search for Users.................................................................................................................8
1.8. Toggle User Account Status...............................................................................................9
1.9. Update User Profile...........................................................................................................10
1.10. Delete User.....................................................................................................................11
2. Authentication & Authorization Service.............................................................................12
2.1. List of Endpoints...............................................................................................................12
2.2. Register User....................................................................................................................14
2.3. Authenticate User.............................................................................................................15
2.4. Logout User......................................................................................................................15
2.5. Request Password Reset.................................................................................................16
2.6. Confirm Password Reset..................................................................................................17
2.7. Change Password.............................................................................................................18
2.8. Retrieve User Roles..........................................................................................................19
2.9. Assign Role to User..........................................................................................................20
2.10. Revoke Role from User...................................................................................................21
2.11. Retrieve Permissions for Role........................................................................................21
2.12. Assign Permission to Role..............................................................................................22
 API Documentation

1. User Management Service

1.1. List of Endpoints

[Link]. API Endpoint Method Description

1. ${baseUrl}/user/register POST Register a

new user.

2. ${baseUrl}/user/profile/:userId GET Fetch the

profile
details of a
specific
user by
their ID.

3. ${baseUrl}/user/profile/:userId PUT Update the

profile
details of a
specific
user by
their ID.

4. ${baseUrl}/user/delete/:userId DELET Delete a

E specific
user by
their ID.

5. ${baseUrl}/user/role/:role GET Retrieve all

users with
a specific
role.

6. ${baseUrl}/user/assignRole/:userId POST Assign a

specific
role to a
user.

7. ${baseUrl}/user/revokeRole/:userId DELET Revoke a

E specific
role from a
user.

8. ${baseUrl}/user/search POST Search for

users
 based on
given
criteria.

9. ${baseUrl}/user/toggleAccountStatus/:userId PUT Toggle the

account
status of a
user (e.g.,
ACTIVE,
INACTIVE)
.

1.2. Register a new user in the system

Register a new user in the system.

Request

Method URL

POST ${baseUrl}/user/register

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN') or hasRole('ROLE_SUPPORT')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source.

POST username string Unique username for the user.

POST email string Email address of the user.

POST password string Password for the user account.

POST firstName string First name of the user.

POST lastName string Last name of the user.

... ... ... ... (You can continue adding other

attributes in a similar manner)

Note: The above table provides a structured format for the ${baseUrl}/user/register endpoint. You
can continue adding other attributes in the POST section as per your requirements.

Response

Status Response

200 { "message": "User registered successfully", "userId": <userId> }

403 {"error":"API key is missing."}

400 {"error":"Username is mandatory."}

400 {"error":"Email is mandatory."}

401 {"error":"Invalid API key."}

409 {"error":"User with this username or email already exists."}

500 {"error":"Something went wrong. Please try again later."}

1.3. Fetch User Profile

Fetch User Profile.

Request

Method URL

GET ${baseUrl}/user/profile/:userId

Authorization Role

@PreAuthorize ("hasRole('ROLE_USER') or hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source.

Note: nil.

Response
 Status Response

200 { "userId": <userId>, "username": <username>, ... }

403 {"error":"API key is missing."}

401 {"error":"Unauthorized."}

404 {"error":"User not found."}

500 {"error":"Something went wrong. Please try again later."}

1.4. Retrieve Users by Role

Retrieve all users with a specific role.

Request

Method URL

GET ${baseUrl}/user/role/:role

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source.

Note: nil.

Response

Status Response

200 [ { "userId": <userId1>, "username": <username1>, ... }, ... ]

403 {"error":"API key is missing."}

401 {"error":"Unauthorized."}

404 {"error":"No users found with the specified role."}

 500 {"error":"Something went wrong. Please try again later."}

1.5. Assign Role to User

Delete a user from the system.

Request

Method URL

POST ${baseUrl}/user/assignRole/:userId

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source.

POST role string The role to be assigned to the user.

Note: nil.

Response

Status Response

200 { "message": "Role assigned successfully" }

403 {"error":"API key is missing."}

401 {"error":"Unauthorized."}

404 {"error":"User not found."}

500 {"error":"Something went wrong. Please try again later."}

1.6. Revoke Role from User

Revoke Role from User.
Request

Method URL

DELETE ${baseUrl}/user/revokeRole/:userId

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source.

DELETE role string The role to be revoked from the user.

Note: nil.

Response

Status Response

200 { "message": "Role revoked successfully" }

403 {"error":"API key is missing."}

401 {"error":"Unauthorized."}

404 {"error":"User not found."}

500 {"error":"Something went wrong. Please try again later."}

1.7. Search for Users

Search for Users.

Request

Method URL

POST ${baseUrl}/user/search
 Authorization Role

@PreAuthorize ("hasRole('ROLE_USER') or hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source.

POST query string Search query (e.g., username, email,

etc.)

Note: nil.

Response

Status Response

200 [ { "userId": <userId1>, "username": <username1>, ... }, ... ]

403 {"error":"API key is missing."}

401 {"error":"Unauthorized."}

404 {"error":"No users found with the specified criteria."}

500 {"error":"Something went wrong. Please try again later."}

1.8. Toggle User Account Status

Toggle the account status of a user (e.g., ACTIVE, INACTIVE).

Request

Method URL

PUT ${baseUrl}/user/toggleAccountStatus/:userId

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

 HEAD api_key string api_key must be sent with all client
requests. The api_key helps the
server to validate the request source.

PUT status string New status for the user account (e.g.,
ACTIVE, INACTIVE).

Note: nil.

Response

Status Response

200 { "message": "User account status updated successfully" }

403 {"error":"API key is missing."}

401 {"error":"Unauthorized."}

404 {"error":"User not found."}

500 {"error":"Something went wrong. Please try again later."}

1.9. Update User Profile

Update the profile details of a specific user by their ID.

Request

Method URL

PUT ${baseUrl}/user/profile/:userId

Authorization Role

@PreAuthorize ("hasRole('ROLE_USER') or hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source.

PUT username string Updated username for the user.

 PUT email string Updated email address for the user.

PUT firstName string Updated first name of the user.

PUT lastName string Updated last name of the user.

... ... ... ... (You can continue adding other

attributes in a similar manner)

Note: nil.

Response

Status Response

200 { "message": "User profile updated successfully" }

403 {"error":"API key is missing."}

401 {"error":"Unauthorized."}

404 {"error":"User not found."}

500 {"error":"Something went wrong. Please try again later."}

1.10. Delete User

Delete a specific user by their ID.

Request

Method URL

DELETE ${baseUrl}/user/delete/:userId

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source.
Note: nil.

Response

Status Response

200 { "message": "User deleted successfully" }

403 {"error":"API key is missing."}

401 {"error":"Unauthorized."}

404 {"error":"User not found."}

500 {"error":"Something went wrong. Please try again later."}

2. Authentication & Authorization Service

2.1. List of Endpoints

[Link]. API Endpoint Method Description

1. ${baseUrl}/auth/register POST Register a

new user.

2. ${baseUrl}/auth/login POST Authenticat

e a user
and return
an access
token.

3. ${baseUrl}/auth/logout POST Invalidate

the current
user’s
access
token.

4. ${baseUrl}/auth/resetPassword POST Request a

password
reset for a
user.

5. ${baseUrl}/auth/confirmReset/:token POST Confirm

the
password
reset using
 a token.

6. ${baseUrl}/auth/changePassword PUT Change

the
password
for the
currently
authenticat
ed user.

7. ${baseUrl}/auth/roles/:userId GET Retrieve all

roles
associated
with a
specific
user.

8. ${baseUrl}/auth/assignRole/:userId/:role POST Assign a

new role to
a user.

9. ${baseUrl}/auth/revokeRole/:userId/:role DELET Revoke a

E role from a
user.

10. ${baseUrl}/auth/permissions/:roleId GET Retrieve all

permission
s
associated
with a
specific
role.

11. ${baseUrl}/auth/assignPermission/:roleId/:permId POST Assign a

specific
permission
to a role.

2.2. Register User

Register a new user in the system.

Request

Method URL

POST ${baseUrl}/auth/register
 Authorization Role

None Public endpoint

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

POST username string Desired username for the user.

POST email string Email address of the user.

POST password string Password for the user account.

... ... ... ... (You can continue adding other

attributes in a similar manner)

Note: nil.

Response

Status Response

201 { "message": "User registered successfully", "userId": <userId> }

403 {"error":"API key is missing."}

409 {"error":"Username or email already exists."}

500 {"error":"Something went wrong. Please try again later."}

2.3. Authenticate User

Authenticate a user and return an access token.

Request

Method URL

POST ${baseUrl}/auth/login

Authorization Role
 None Public endpoint

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

POST username string Username of the user.

POST password string Password of the user.

Note: nil.

Response

Status Response

200 { "message": "Authentication successful", "token": <accessToken> }

403 {"error":"API key is missing."}

401 {"error":"Invalid credentials."}

500 {"error":"Something went wrong. Please try again later."}

2.4. Logout User

Invalidate the current user’s access token.

Request

Method URL

POST ${baseUrl}/auth/logout

Authorization Role

@PreAuthorize ("isAuthenticated()")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
 server to validate the request source

HEAD Authorization string Bearer token for the authenticated

user.

Note: nil.

Response

Status Response

200 { "message": "Logout successful" }

403 {"error":"API key is missing."}

401 {"error":"Invalid token."}

500 {"error":"Something went wrong. Please try again later."}

2.5. Request Password Reset

Request a password reset for a user.

Request

Method URL

POST ${baseUrl}/auth/resetPassword

Authorization Role

None Public endpoint

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

POST email string Email address of the user requesting

the password reset.

Note: nil.

Response
 Status Response

200 { "message": "Password reset link sent to email." }

403 {"error":"API key is missing."}

404 {"error":"User with this email not found."}

500 {"error":"Something went wrong. Please try again later."}

2.6. Confirm Password Reset

Request a password reset for a user.

Request

Method URL

POST ${baseUrl}/auth/confirmReset/:token

Authorization Role

None Public endpoint

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

POST newPassword string New password for the user.

Note: nil.

Response

Status Response

200 { "message": "Password reset successful." }

403 {"error":"API key is missing."}

400 {"error":"Invalid or expired token."}

 500 {"error":"Something went wrong. Please try again later."}

2.7. Change Password

Change the password for the currently authenticated user.

Request

Method URL

PUT ${baseUrl}/auth/changePassword

Authorization Role

@PreAuthorize ("isAuthenticated()")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

HEAD Authorization string Bearer token for the authenticated

user.

POST oldPassword string Current password of the user.

POST newPassword string New password for the user.

Note: nil.

Response

Status Response

200 { "message": "Password changed successfully." }

403 {"error":"API key is missing."}

401 {"error":"Invalid current password."}

500 {"error":"Something went wrong. Please try again later."}

2.8. Retrieve User Roles
Retrieve all roles associated with a specific user.

Request

Method URL

GET ${baseUrl}/auth/roles/:userId

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

Note: nil.

Response

Status Response

200 { "roles": ["ROLE_USER", "ROLE_ADMIN"] }

403 {"error":"API key is missing."}

404 {"error":"User not found."}

500 {"error":"Something went wrong. Please try again later."}

2.9. Assign Role to User

Assign a new role to a user.

Request

Method URL

POST ${baseUrl}/auth/assignRole/:userId/:role
 Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

Note: nil.

Response

Status Response

200 { "message": "Role assigned successfully." }

403 {"error":"API key is missing."}

404 {"error":"User or role not found."}

500 {"error":"Something went wrong. Please try again later."}

2.10. Revoke Role from User

Revoke a role from a user.

Request

Method URL

DELETE ${baseUrl}/auth/revokeRole/:userId/:role

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source
Note: nil.

Response

Status Response

200 { "message": "Role revoked successfully." }

403 {"error":"API key is missing."}

404 {"error":"User or role not found."}

500 {"error":"Something went wrong. Please try again later."}

2.11. Retrieve Permissions for Role

Retrieve all permissions associated with a specific role.

Request

Method URL

GET ${baseUrl}/auth/permissions/:roleId

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

Note: nil.

Response

Status Response

200 { "permissions": ["READ_COURSE", "EDIT_COURSE"] }

 403 {"error":"API key is missing."}

404 {"error":"Role not found."}

500 {"error":"Something went wrong. Please try again later."}

2.12. Assign Permission to Role

Assign a specific permission to a role.

Request

Method URL

POST ${baseUrl}/auth/assignPermission/:roleId/:permId

Authorization Role

@PreAuthorize ("hasRole('ROLE_ADMIN')")

Type Params Values Remarks

HEAD api_key string api_key must be sent with all client

requests. The api_key helps the
server to validate the request source

Note: nil.

Response

Status Response

200 { "message": "Permission assigned successfully." }

403 {"error":"API key is missing."}

404 {"error":"Role or permission not found."}

500 {"error":"Something went wrong. Please try again later."}