-
Notifications
You must be signed in to change notification settings - Fork 5
RESTful services documentation
Katrina Poulin edited this page Mar 2, 2020
·
31 revisions
[intro] The base URL is petshelter-backend.herokuapp.com.
See the http status codes there: https://www.restapitutorial.com/httpstatuscodes.html
Most of our methods take in as a parameter a token to authenticate the user.
- User
- Pet
- Advertisement
- Donation
- Application
- Comment
- Forum
Note: The parameter String token is used to authenticate the user's session, i.e. to make sure it has not expired and that the user is logged in.
| Request type | Endpoints | Method Description | Inputs | Outputs |
|---|---|---|---|---|
| GET | api/user/registrationConfirmation | Confirms the registration of a specific user. | @RequestParam String token - Requester's session validation token | Success: Http 200 (User registered) Failure: Http 400 (Token not found or account already validated), Http 503 (Token expired) |
| GET | api/user/{username} | Gets user by username. | @PathVariable String username - Requested user's username, @RequestHeader String token - Requester's session validation token | Success: Http 200 (UserDto - Requested user) Failure: Http 400 (User not found or requester unauthorized) |
| GET | api/user/all | Gets all users in the database. | @RequestHeader String token - Requester's session validation token | Success: Http 200 (List of UserDtos) Failure: Http 400 (Requester not an admin), Http 500 (Not found) |
| PUT | api/user/{username} | Updates a given user's username. | @RequestHeader String token - Requester's session validation token, @PathVariable String username - User to be updated's username, @RequestBody UserDto updatedUser - User with updated parameters | Success: Http 200 (UserDto, updated user), Failure: Http 400 (No user found or invalid username) |
| DELETE | api/user/{username} | Deletes a given user. | @PathVariable String username - User to be deleted's username, @RequestHeader String token - Requester's session validation token | Success: Http 200 (User deleted) Failure: Http 500 (User could not be deleted), Http 400 (Requester is not an admin) |
| POST | api/user/register | Registers a new user in the database. | @RequestBody UserDto user - User to be registered | Success: Http 201 (UserDto - the created user) Failure: Http 400 (Email/Username already in use), Http 500 (Confirmation email cannot be sent) |
| POST | api/user/login | Login a given user to the petShelter system. | @RequestBody UserDto user - User requesting to login | Success: Http 200 (UserDto - the logged in user) Failure: Http 400 (Incorrect username, password, or account not verified) |
| POST | api/user/resetPassword | Resets the password of an account defined by an email. | @RequestBody String email - Email of the user requesting a password reset | Success: Http 200 (Password is reset) Failure: Http 400 (Account not verified or no user found), Http 500 (Password reset failed) |
| POST | api/user/changePassword | Changes the password of a given user. | @RequestBody ChangePasswordDTO user - User requesting a password change, @RequestHeader String token - Requester's session validation token | Success: Http 200 (UserDto - the changed user) Failure: Http 400 (Illegal password, Requester unauthorized) |
| POST | api/user/logout | Logout a given user from the petShelter system. | @RequestHeader String token - Requester's session validation token | Success: Http 200 (User logged out) Failure: Http 400 (No user logged in) |
| Request type | Endpoints | Method Description | Inputs | Outputs |
|---|---|---|---|---|
| GET | api/pet/{id} | Gets a pet by petID. | @RequestHeader String token - Requester's session validation token, @PathVariable long id - the ID of the requested pet | Success: Http 200 (Pet found and returned) Failure: Http 400 (User not found, Pet not found) |
| GET | api/pet/all | Gets all pets in the database. | @RequestHeader String token - Requester's session validation token | Success: Http 200 (List of PetDtos) Failure: Http 400 (No user found) |
| GET | api/pet/all/user/{user} | Gets all pets belonging to a given user. | @RequestHeader String token - Requester's session validation token, @PathVariable String username - username of the user owning the requested pets | Success: Http 200 (List of PetDto - pets belonging to the requested user) Failure: Http 400 (Requester not found) |
| GET | api/pet/all/ad/{advertisement} | Gets all pets related to a given advertisement. | @RequestHeader String token - Requester's session validation token, @PathVariable long advertisement - ID of the advertisement linked to the requested pets | Success: Http 200 (List of PetDTO returned) Failure: Http 400 (Requester not found) |
| DELETE | api/pet/{id} | Deletes a pet from the database. | @RequestHeader String token - Requester's session validation token, @PathVariable long id - ID of the pet to be deleted | Success: Http 200 (Pet deleted) Failure: Http 400 (Requester not found) |
| PUT | api/pet/update | Updates the parameters of a given pet. | @RequestHeader String token - Requester's session validation token, @RequestBody PetDto pet - Pet to be updated | Success: Http 200 (Pet updated) Failure: Http 400 (Requester not found) |
| PUT | api/pet/changeOwner | Changes ownership of a pet from one user to another. | @RequestHeader String token - Requester's session validation token, @RequestBody PetDto pet - Pet to be changed owners | Success: Http 200 (MOdified pet) Failure: Http 400 (Requester not found) |
| POST | api/pet/ | Creates new pet in the database. | @RequestHeader String token - Requester's session validation token, @RequestBody PetDto pet - Pet to be created | Success: Http 201 (Pet created, petDTO returned) Failure: Http 400 (Requester not found or is not the pet's owner) |
| Request type | Endpoints | Method Description | Inputs | Outputs |
|---|---|---|---|---|
| GET | api/advertisement/id/{adId} | Gets an advertisement by ID. | @RequestParam String token - Requester's session validation token, @PathVariable long adId - ID of the requested advertisement | Success: Http 200 (AdvertisementDto returned) Failure: Http 400 (Requester or advertisement not found) |
| GET | api/advertisement/{title} | Gets all advertisements with a given title. | @RequestBody String token - Requester's session validation token, @PathVariable String title - title of the requested advertisements | Success: Http 200 (AdvertisementDto returned) Failure: Http 400 (Requester not found) |
| GET | api/advertisement/all | Gets all advertisements in the database. | @RequestBody String token - Requester's session validation token | Success: Http 200 (List of AdvertisementDto returned) Failure: Http 400 (Requester not found) |
| POST | api/advertisement/{petId}/newAd | Creates a new advertisement linked to a pet. | @RequestBody String token - Requester's session validation token, @PathVariable long petId - ID of the pet for which an advertisement is requested | Success: Http 201 (AdvertisementDto created) Failure: Http 400 (Invalid advertisement, Unauthorized user) |
| PUT | api/advertisement/ | Updates a given advertisement. | @RequestBody String token - Requester's session validation token, @RequestBody AdvertisementDto advertisement - advertisement to be updated | Success: Http 200 (AdvertisementDto returned) Failure: Http 400(Requester not found, invalid pets) |
| DELETE | api/advertisement/{adId} | Deletes a given advertisement from the database. | @RequestBody String token - Requester's session validation token, @PathVariable long adId - ID of the advertisement to be deleted | Success: Http 200 (Advertisement deleted) Failure: Http 401 (Requester not found, advertisement not found) |
| Request type | Endpoints | Method Description | Inputs | Outputs |
|---|---|---|---|---|
| GET | api/donation/all | Gets all the donations in the database. | @RequestHeader String token - Requester's session validation token | Success: Http 200 (List of DonationDto returned) Failure: Http 400 (Unauthorized requester) |
| GET | api/donation/{user} | Gets all donations made by a given user. | @RequestHeader String token - Requester's session validation token, @PathVariable String user - User which we want to query the donations from | Success: Http 200 (List of DonationDto returned) Failure: Http 400 (Unauthorized requester) |
| POST | api/donation/ | Creates a new donation in the database. | @RequestHeader String token - Requester's session validation token, @RequestBody DonationDto donation - Donation to be created | Success: Http 200 (Donation created) Failure: Http 400 (Illegal amount) |
| Request type | Endpoints | Method Description | Inputs | Outputs |
|---|---|---|---|---|
| GET | api/application/all | Gets all applications in the database. | @RequestHeader String token - Requester's session validation token | Success: Http 200 (List of ApplicationDto returned) Failure: Http 400 (Requester not found) |
| GET | api/application/allAccepted | Gets all advertisements selected for adoption. | @RequestHeader String token - Requester's session validation token | Success: Http 200 (List of ApplicationDto returned) Failure: Http 400 (Requester not found) |
| GET | api/application/allUnaccepted | Gets all advertisements not selected for adoption. | @RequestHeader String token - Requester's session validation token | Success: Http 200 (List of ApplicationDto returned) Failure: Http 400 (Requester not found) |
| GET | api/application/{user} | Gets all applications for a given user. | @RequestHeader String token - Requester's session validation token, @PathVariable String user - username of the applicant of whom we are requesting applications | Success: Http 200 (List of ApplicationDto returned) Failure: Http 400 (Requester not found) |
| POST | api/application/ | Creates new application in the database. | @RequestHeader String token - Requester's session validation token, @RequestBody ApplicationDto application - Application to be created | Success: Http 200 (ApplicationDto created/returned) Failure: Http 400 (Illegal application, Requester not found) |
| DELETE | api/application/{applicationId} | Deletes a given advertisement from the database. | @RequestHeader String token - Requester's session validation token, @PathVariable long applicationId - ID of the application to be deleted | Success: Http 200 (Application deleted) Failure: Http 401 (Requester unauthorized) |
| PUT | api/application/{applicationId} | Updates a given application. | @RequestHeader String token - Requester's session validation token, @PathVariable long applicationId - ID of the application to be modified, @RequestBody ApplicationDto application | Success: Http 200 (ApplicationDto returned) Failure: Http 401 (Requester unauthorized) |
| Request type | Endpoints | Method Description | Inputs | Outputs |
|---|---|---|---|---|
| GET | api/comment/all/{threadId} | Gets all the comments in a given thread. | @RequestHeader String token - Requester's session validation token, @PathVariable long threadId - ID of the thread for which we are requesting the comments | Success: Http 200 (List of CommentDto returned) Failure: Http 400 (Unauthorized requester) |
| GET | api/comment/{username} | Gets all the comments posted by a given user. | @RequestHeader String token - Requester's session validation token, @PathVariable String username - username of the user for which we are requesting comments | Success: Http 200 (List of CommentDto returned) Failure: Http 400 (Requester not found) |
| POST | api/comment/{id} | Creates a comment in a given thread. | @RequestHeader String token - Requester's session validation token, @PathVariable long id - ID of the thread, @RequestBody String commentText - Text content of the new comment | Success: Http 201 (CommentDto created/returned)Failure: Http 400 (Requester not found, illegal comment) |
| PUT | api/comment/{id}/{commentId} | Updates a comment in a given thread. | @RequestHeader String token - Requester's session validation token, @PathVariable long id - ID of the thread, @RequestBody CommentDto comment - updated comment, @PathVariable long commentId | Success: Http 200 (CommentDto returned) Failure: Http 400 (Comment not found, Unauthorized requester) |
| DELETE | api/comment/{id}/{commentId} | Deletes a given comment in a given thread. | @RequestHeader String token - Requester's session validation token, @PathVariable long id - ID of the thread, @PathVariable long commentId - the ID of the comment to be deleted | Success: Http 200 (Comment deleted) Failure: Http 400 (Requester not found, Unauthorized requester) |
| Request type | Endpoints | Method Description | Inputs | Outputs |
|---|---|---|---|---|
| GET | api/forum/{id} | Gets a given forum. | @RequestHeader String token - Requester's session validation token, @PathVariable long id - ID of the requested forum | Success: Http 200 (ForumDto returned) Failure: Http 400 (Requester not found) |
| GET | api/forum/forums/{username} | Gets all the forums owned by a given user. | @RequestHeader String token - Requester's session validation token, @PathVariable String username - username of the owner of the requested forums | Success: Http 200 (List of ForumDto returned) Failure: Http 400 (Requester not found) |
| GET | api/forum/all | Gets all forums in the database. | @RequestHeader String token - Requester's session validation token | Success: Http 200 (List of ForumDto returned) Failure: Http 400 (Requester not found) |
| POST | api/forum/ | Creates a new forum in the database. | @RequestHeader String token - Requester's session validation token, @RequestBody String title - Title of the requested forum | Success: Http 201 (ForumDto returned) Failure: Http 400 (Requester not found, illegal forum parameters) |
| PUT | api/forum/{forumId} | Updates a given forum. | @RequestHeader String token - Requester's session validation token, @PathVariable long forumId - ID of the forum, @RequestBody String forumTitle - New title of the forum | Success: Http 200 (ForumDto created) Failure: Http 400 (Requester not found, Unauthorized requester) |
| PUT | api/forum/lock/{forumId} | Locks/Unlocks a given forum. | @RequestHeader String token - Requester's session validation token, @PathVariable long forumId - ID of the forum to be locked, @RequestBody Boolean isLocked - True if locked, false if unlocked | Success: Http 200 (ForumDto returned) Failure: Http 400 (Unauthorized requester) |
| PUT | api/forum/subscribe/{forumId} | Subscribes a given user to a given forum. | @RequestHeader String token - Requester's session validation token, @PathVariable long forumId - ID of the forum to subscribe to | Success: Http 200 (ForumDto returned) Failure: Http 400 (Requester not found, forum not found) |
| PUT | api/forum/unsubscribe/{forumId} | Unsubscribes a given user from a given forum. | @RequestHeader String token - Requester's session validation token, @PathVariable long forumId - ID of the forum to unsubscribe from | Success: Http 200 (ForumDto created) Failure: Http 400 (Requester not found, forum not found) |
| DELETE | api/forum/{forumId} | Deletes a given forum from the database. | @RequestHeader String token - Requester's session validation token, @PathVariable long forumId - ID of the forum to be deleted | Success: Http 200 (Forum deleted) Failure: Http 400 (Unauthorized requester, forum not found) |