API Documentation - WassimJabz/Purposeful GitHub Wiki

API Documentation

Our project has extensive java documentation that be found in the mmss/javadoc folder, that also describes the way each controller method is RESTfully exposed. The endpoint of every method is described here, with details available under each dropdown.

Endpoint Naming Convention: /api/classname. This lets you have one POST, PUT, GET, DELETE. If you need to make it unique, go for /api/classname/detail, where the detail is a noun, not a verb ( no actions :) ). Eg. we could have a post method at /api/appuser/moderator and api/appuser/regularuser for the appuser controller.

Notes For Controllers:

  • Use @RequestBody for parameters that are Dtos
  • Use @RequestParam for parameters that are passed through the url, with /api/classname?parameterName=value

Login

POST: /api/login, /api/login/

Description

Login an account to the Purposeful app

Parameters

A custom header is required for authentication with the form: "Authorization": "Base ${base64(username:password)}"

Return Values

A JWT token if the provided username and password matched, 401 Unauthorized otherwise.

GET: /api/login, /api/login/

Description

Verify that a token is valid, i.e. an user is logged in.

Parameters

None, only the custom header is required for authentication with the form: "Authorization": "Bearer token".

Return Values

An appUserDTO:

{
    "id": "String",
    "email": "String",
    "password": "",
    "firstname": "String",
    "lastname": "String"
}

or 401 Unauthorized otherwise.

GET: /login/employee (Example from 321)

Description

Login an employee

Parameters

String username a request parameter, the username of the employee
String password a request parameter, the password of the employee

Return Values

An EmployeeDto

{ 
"phoneNumber" : "String",
"userName": "String",
"personId": "int",
"communicationId": "int"
}

App User

GET: /api/appuser/users

Description

Allows to get all users in the system

Return Values

{
    "id": "String",
    "email": "String",
    "password": "",
    "firstname": "String",
    "lastname": "String"
}

Test:

Screenshot 2023-02-21 at 5 41 29 PM
POST: /api/appuser/regular

Description

Allows someone to register a new regular user account when they are not logged in

Parameters

AppUserDto appUserDto - the user to be registered

  • String email
  • String password
  • String firstname
  • String lastname

Return Values

{
    "id": "String",
    "email": "String",
    "password": "",
    "firstname": "String",
    "lastname": "String"
}
POST: /api/appuser/moderator

Description

Allows the owner to register a new moderator account

Parameters

AppUserDto appUserDto - the user to be registered

  • String email
  • String password
  • String firstname
  • String lastname

Return Values

{
    "id": "String",
    "email": "String",
    "password": "",
    "firstname": "String",
    "lastname": "String"
}
PUT: /api/appuser/regular

Description

Allows the Owner, Admin and Regular users to modify the names of the given account

Parameters

AppUserDto appUserDto - the user to be modified

  • String email
  • String firstname
  • String lastname

Return Values

{
    "id": "String",
    "email": "String",
    "password": "",
    "firstname": "String",
    "lastname": "String"
}

Tests

Successful modification:

Screenshot 2023-02-21 at 5 26 20 PM

Test that errors are thrown correctly:

Screenshot 2023-02-21 at 5 26 36 PM
PUT: /api/appuser/regular/password

Description

Allows the Owner, Admin and Regular users to modify the password of a given account

Parameters

AppUserDto appUserDto - the user to be modified

  • String email
  • String password

Return Values

{
    "id": "String",
    "email": "String",
    "password": "",
    "firstname": "String",
    "lastname": "String"
}

Tests

Successful modification:

Screenshot 2023-02-21 at 5 23 36 PM

Test that errors are thrown correctly:

Screenshot 2023-02-21 at 5 23 24 PM Screenshot 2023-02-21 at 5 25 40 PM
PUT: /api/appuser/moderator

Description

Allows the Owner and Admin accounts to modify the names of the given moderator account

Parameters

AppUserDto appUserDto - the user to be modified

  • String email
  • String firstname
  • String lastname

Return Values

{
    "id": "String",
    "email": "String",
    "password": "",
    "firstname": "String",
    "lastname": "String"
}

Tests

Successful modification:

Test that errors are thrown correctly:

Screenshot 2023-02-21 at 5 33 22 PM Screenshot 2023-02-21 at 5 34 15 PM
PUT: /api/appuser/moderator/password

Description

Allows the Owner and Admin to modify the password of a moderator account

Parameters

AppUserDto appUserDto - the moderator to be modified

  • String email
  • String password

Return Values

{
    "id": "String",
    "email": "String",
    "password": "",
    "firstname": "String",
    "lastname": "String"
}

Tests

Successful modification:

Test that errors are thrown correctly:

Screenshot 2023-02-21 at 5 39 09 PM Screenshot 2023-02-21 at 5 39 29 PM

Idea

GET: /api/idea/{id}

Description

Get an idea from the Purposeful App using its id

Parameters

String id: the idea's id

Return Value

An IdeaDTO

{
    "id": "string",
    "isPaid": "boolean",
    "isPrivate": "boolean",
    "inProgress": "boolean",
    "title": "string",
    "purpose": "string",
    "description": "string",
    "date": "YYYY-MM-DD",
    "domains": ["domainDTOs"],
    "techs": ["techDTOs"],
    "topics": ["topicDTOs"],
    "imgUrls": ["urlDTOs"],
    "iconUrl": {"urlDTO"}
}
GET: /api/idea/user

Description

Get all created ideas of logged in user from the Purposeful App

Parameters

N/A

Return Value

An ArrayList of IdeaDTOs

[{
    "id": "string",
    "isPaid": "boolean",
    "isPrivate": "boolean",
    "inProgress": "boolean",
    "title": "string",
    "purpose": "string",
    "description": "string",
    "date": "YYYY-MM-DD",
    "domains": ["domainDTOs"],
    "techs": ["techDTOs"],
    "topics": ["topicDTOs"],
    "imgUrls": ["urlDTOs"],
    "iconUrl": {"urlDTO"}]
}
POST: /api/idea

Description

Returns all public criteria with the given search filters.

Parameters

A SearchFilterDTO

{
    "domains": "List<String>",
    "topics": "List<String>",
    "technologies": "List<String>"
}

Return Value

An IdeaDTO list

{
    "id": "string",
    "isPaid": "boolean",
    "isPrivate": "boolean",
    "inProgress": "boolean",
    "title": "string",
    "purpose": "string",
    "description": "string",
    "date": "YYYY-MM-DD",
    "domains": ["domainDTOs"],
    "techs": ["techDTOs"],
    "topics": ["topicDTOs"],
    "imgUrls": ["urlDTOs"],
    "iconUrl": {"urlDTO"}
}
POST: /api/idea/create

Description

Creates an idea in the Purposeful App

Parameters

An IdeaRequestDTO

{
    "id": null,
    "isPaid": "boolean",
    "isPrivate": "boolean",
    "inProgress": "boolean",
    "date": null,
    "title": "string",
    "purpose": "string",
    "description": "string",
    "domainIds": ["domainId1","domainId2"],
    "techIds": ["techIds"],
    "topicIds": ["topicIds"],
    "imgUrls": ["urls"],
    "iconUrl": {"url"}
}

Here is an example of how to create an idea. Replace the Ids of the Domain Topic and Tech with the updated ones you get from the database.

{
    "id": null,
    "isPaid":true,
    "isPrivate":true,
    "inProgress":true,
    "title":"test_post",
    "purpose":"testing",
    "description":"just_a_test",
    "date":null,
    "domainIds":["bc672312-198c-47b8-839a-ba8a5ce3f745"],
    "techIds":["40b47982-a40c-4364-8915-e408bcb6b571"],
    "topicIds":["981e08dc-89b6-490f-b0e1-99bee9e9b188"],
    "imgUrls":["https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRjAo08bvUmiFOqrYCYh6VeCUQKPzkORdENovFsBGWG7A&s"],
    "iconUrl":"https://cdn.thecoolist.com/wp-content/uploads/2016/05/Japanese-Cherry-beautiful-tree.jpg"
}

Return Value

An IdeaRequestDTO

{
    "id": "a323bdw2-sad8-mte9-n2k3-3nr920mds9d8",
    "isPaid":true,
    "isPrivate":true,
    "inProgress":true,
    "title":"test_post",
    "purpose":"testing",
    "description":"just_a_test",
    "date":null,
    "domainIds":["bc672312-198c-47b8-839a-ba8a5ce3f745"],
    "techIds":["40b47982-a40c-4364-8915-e408bcb6b571"],
    "topicIds":["981e08dc-89b6-490f-b0e1-99bee9e9b188"],
    "imgUrls":["https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRjAo08bvUmiFOqrYCYh6VeCUQKPzkORdENovFsBGWG7A&s"],
    "iconUrl":"https://cdn.thecoolist.com/wp-content/uploads/2016/05/Japanese-Cherry-beautiful-tree.jpg"
}
PUT: /api/idea/edit

Description

Modify an idea from the Purposeful App

Parameters

An IdeaRequestDTO

{
    "id": "string",
    "isPaid": "boolean",
    "isPrivate": "boolean",
    "inProgress": "boolean",
    "title": "string",
    "purpose": "string",
    "description": "string",
    "date": "YYYY-MM-DD",
    "domains": ["domainIds"],
    "techs": ["techIds"],
    "topics": ["topicIds"],
    "imgUrls": ["urls"],
    "iconUrl": {"url"}
}

Return Value

An IdeaRequestDTO

{
    "id": "string",
    "isPaid": "boolean",
    "isPrivate": "boolean",
    "inProgress": "boolean",
    "title": "string",
    "purpose": "string",
    "description": "string",
    "date": "YYYY-MM-DD",
    "domains": ["domainIds"],
    "techs": ["techIds"],
    "topics": ["topicIds"],
    "imgUrls": ["urls"],
    "iconUrl": {"url"}
}
DELETE: /api/idea/{id}

Description

Remove an idea from the Purposeful App using its id

Parameters

String id: the idea's id

Return Values

A response entity with a message instance and the HttpStatus

GET: /api/idea/user/requests

Description

Get all ideas that the user provided has requested to collaborate on.

Return Value

List of IdeaDTO

{
    "id": "string",
    "isPaid": "boolean",
    "isPrivate": "boolean",
    "inProgress": "boolean",
    "title": "string",
    "purpose": "string",
    "description": "string",
    "date": "YYYY-MM-DD",
    "domains": ["domainDTOs"],
    "techs": ["techDTOs"],
    "topics": ["topicDTOs"],
    "imgUrls": ["urlDTOs"],
    "iconUrl": {"urlDTO"}
}

Reaction

POST: /api/reaction, /api/reaction/

Description

React to an idea on the Purposeful App

Parameters

reactionRequestDTO DTO of the request for a reaction to be added or removed

  • ReactionType reactionType
  • String idea_id
  • String user_id

Return Values

The newly created reaction DTO

{ 
"id" : null
"date" : "Date",
"reactionType": "ReactionType" ,
"idea_id": "String" ,
"user_id": "String" 
}

CollaborationResponse

GET: /api/collaborationResponse/{ideaId}

Description

Get a CollaborationResponse from the Purposeful App using the ideaId and associated user (from login)

Parameters

String ideaId: the id of the idea associated with the response

Return Value

A CollaborationResponseDTO

{
    "id": "string",
    "message": "string",
    "additionalContact": "string"
}
POST: /api/collaborationResponse/approve

Description

Approves a collaboration request

Parameters

A collaborationResponseInformationDTO.

{ 
    "collaborationRequestId": "string",
    "message": "string",
    "additionalContact": "string"
}

Return Value

A CollaborationResponseDTO

{ 
    "id": "string",
    "message": "string",
    "additionalContact": "string"
}
POST: /api/collaborationResponse/decline

Description

Declines a collaboration request

Parameters

A CollaborationResponseDTO

{ 
    "id": "string",
    "message": "string",

}

Return Value

A CollaborationResponseDTO

{ 
    "id": "string",
    "message": "string",
    "additionalContact": "string"
}

CollaborationRequest

POST: /api/collaborationRequest

Description

Sends a collaboration request

Parameters

collaborationRequestDTO The DTO containing the idea, the message, and the additional contact information

{ 
"ideaId" : "String",
"message": "String" ,
"additionalContact": "String" 
}

Return Values

A CollaborationRequestDTO

{
    "id": "String",
    "ideaId": "String",
    "message": "String",
    "additionalContact": "String",
    "hasResponse": "boolean"
}

Domain

DTO

JSON

{
    "id": "uuid",
    "name": "string"
}

Technology

DTO

JSON

{
    "id": "uuid",
    "name": "string"
}

Topic

DTO

JSON

{
    "id": "uuid",
    "name": "string"
}

URL

DTO

JSON

{
    "id": "uuid",
    "url": "string",
    "presetIcon": "boolean"
}

Class Name

GET/POST/PUT/DELETE: /pathToEndpoint

Description

Description of what endpoint does

Parameters

type parameter description of parameter

Return Values

{ 
"id": "String",
"message": "String",
"additionalContact": "String",
"status": "Status" 
}
⚠️ **GitHub.com Fallback** ⚠️