JCL

FEUP/DEI & INESC TEC

User Tools

Site Tools


teach:lbaw:medialib:a07

Web Resources Documentation (A7)

The architecture of the web application to develop is documented indicating the catalogue of resources and the properties of each resource, including: references to the graphical interfaces, and the format of JSON responses. This page presents the documentation for MediaLibrary, including the following operations over data: create, read, update, and delete.

1. Overview

An overview of the web application to implement is presented in this section, where the modules are identified and briefly described. The web resources associated with each module are detailed in the individual documentation of each module.

M01: Authentication and Individual Profile Web resources associated with user authentication and individual profile management, includes the following system features: login/logout, registration, credential recovery, view and edit personal profile information.
M02: Works Web resources associated with library items, includes the following system features: items list and search, view and edit item details, and delete items.
M03: Reviews and Wish list Web resources associated with reviews and wish list, includes the following system features: add review, list reviews and delete reviews; add items to wish list and remove items from the wish list.
M04: Loans Web resources associated with loans, includes the following system features: view loans, add loans and edit loans.
M05: User Administration and Static pages Web resources associates with user management, specifically: view and search users, delete or block user accounts, view and change user information, and view system access details for each user. Web resources with static content are associated with this module: dashboard, about, contact, services and faq.

2. Permissions

This section defines the permissions used in the modules to establish the conditions of access to resources.

PUB Public Users without privileges
USR User Authenticated users
OWN Owner User that are owners of the information (e.g. own profile, own itens)
ADM Administrator Administrators

3. Modules

This section documents each web resource of each module, indicating the URL, HTTP methods, the possible parameters (mandatory or optional), body request, interfaces with the user (referring to the A3 artefact), or JSON responses in the event of AJAX call to the API.

Module M01: Authentication and Individual Profile

Endpoints of Module Authentication and Individual Profile

  • R101: Login Form [/login]
  • R102: Login Action [/login]
  • R103: Logout Action [/logout]
  • R104: Register Form [/register]
  • R105: Register Action [/register]
  • R106: View Profile [/users/{id}]
  • R107: Edit Profile Form [/users/{id}/edit]
  • R108: Edit Profile Action [/users/{id}]
  • R109: Password Reset Form [/password/reset]
  • R110: Password Reset Action [/password/reset]

R101: Login Form

URL /login
Description Page with a form to login to a user account.
Method GET
UI UI06
SUBMIT R102
Permissions PUB

R102: Login Action

URL /login
Description This web resource logs the user into the system. Redirects to the user profile page on success and the login form on failure.
Method POST
Request Body +email: string Username
+password: string Password
Redirects R106 Success
R101 Error
Permissions PUB

R103: Logout Action

URL /logout
Description This web resource logs out the authenticated user or admin.
Method POST
Redirects R101 Success
Permissions USR, ADM

R104: Register Form

URL /register
Description Page with a form to register a new user account.
Method GET
UI UI07
SUBMIT R105
Permissions PUB

R105: Register Action

URL /register
Description This web resource inserts the user into the system. Redirects to the user profile page on success and the register form on failure.
Method POST
Request Body +name: string Name
+email: string Email
+password: string Password
?picture: file Profile picture
Redirects R106 Success
R104 Error
Permissions PUB

R106: View Profile

URL /users/{id}
Description Shows the user individual profile page.
Method GET
Parameters +id: integer user primary key
UI UI14
Permissions USR

R107: Edit Profile Form

URL /users/{id}/edit
Description Page with a form to edit profile info.
Method GET
Parameters +id: integer user primary key
UI N/A
SUBMIT R108
Permissions OWN

R108: Edit Profile Action

URL /users/{id}
Description Web resource that changes user profile info based on the input received. Redirects to the user profile on success and edit profile page on failure.
Method POST
Parameters +id: integer user primary key
Request Body ?name: string New name
?picture: file New profile picture
Redirects R106 Success
R107 Error
Permissions OWN

R109: Password recovery Form

URL /password/reset
Description Page with a form to request a token to reset the password.
Method GET
UI UI01
SUBMIT R110
Permissions PUB

R110: Password recovery Action

URL /password/reset
Description Web resource that sends a reset password link to the specified email.
Method POST
Request Body +email: string User email
Redirects UI01 Success
R109 Error
Permissions PUB

Module M02: Works

Endpoints of Module Works

  • R201: Search Work Page [/works]
  • R202: Search Work API [/api/works]
  • R203: View Work [/works/{id}]
  • R204: Add Work Form [/works/create]
  • R205: Add Work Action [/works]
  • R206: Edit Work Form [/works/{id}/edit]
  • R207: Edit Work Action [/works/{id}]
  • R208: Add Item Form [/works/{id}/items/create]
  • R209: Add Item Action [/works/{id}/items]
  • R210: Delete Work Action [/works/{id}]
  • R211: Delete Item Action [/works/{work_id}/items/{item_id}]

R201: Search Work Page

URL /works
Description Page with a form to search works.
Method GET
Parameters ?query: string String field to search for in works
?item: string Category of the work
?loaned: boolean Boolean with the loaned flag value
?owner: boolean Boolean with the owner flag value
?classification: integer Integer with the work classification
UI UI12
AJAX Calls R202
Permissions PUB

R202: Search Work API

URL /api/works
Description This web resource searches the system for works and returns the results.
Method GET
Parameters ?query: string String field to search for in works
?item: string Category of the work
?loaned: boolean Boolean with the loaned flag value
?owner: boolean Boolean with the owner flag value
?classification: integer Integer with the work classification
Response body JSON202
Permissions PUB

R203: View Work

URL /works/{id}
Description Shows the works's page.
Method GET
Parameters +id: integer Work primary key.
UI UI11
Permissions USR

R204: Add Work Form

URL /works/create
Description Page with a form to post a new work.
Method GET
UI UI13
SUBMIT R205
Permissions USR

R205: Add Work Action

URL /works
Description Web resource that creates a new work based on the input received. Redirects to the new work page on success and back to new work form on failure.
Method POST
Request body +name: string Name of the Work
+type: string Type of the Work
+obs: string Observations of the Work
+year: integer Year of the Work
+category: string Category of the Work
+Author: string Author of the Work
?Collection: string Collection of the Work
?edition: string Edition of the Book
?isbn: string ISBN of the Book
?publisherName: string Category of the Book publisher
?picture: file Work picture
Redirects R203 Success
R204 Error
Permissions USR, OWN

R206: Edit Work Form

URL /works/{id}/edit
Description Page with a form to edit work info.
Method GET
Parameter +id: integer work id
UI N/A
SUBMIT R207
Permissions OWN, ADM

R207: Edit Work Action

URL /works/{id}
Description Web resource that changes user profile info based on the input received. Redirects to the user profile on success and edit profile page on failure.
Method PUT
Parameter +id: integer work id
Request Body ?name: string Name of the Work
?type: string Type of the Work
?obs: string Observations of the Work
?year: integer Year of the Work
?category: string Category of the Work
?Author: string Author of the Work
?Collection: string Collection of the Work
?edition: string Edition of the Book
?isbn: string ISBN of the Book
?publisherName: string Category of the Book publisher
?picture: file Work picture
Redirects R203 Success
R206 Error
Permissions OWN

R208: Add Item Form

URL /works/{id}/items/create
Description Page with a form to post a new item.
Method GET
Parameter +id: integer work id
UI N/A
SUBMIT R209
Permissions OWN

R209: Add Item Action

URL /works/{id}/items
Description Web resource that creates a new item based on the input received. Redirects to the work page on success and back to new item form on failure.
Method POST
Parameter +id: integer work id
Request body +code: integer Code of the Item
+date: date Date of the Item creation
+locationName: string Nome of the item location
+address: string Address of the item location
+gps: string GPS coords of the item location
Redirects R203 Success
R208 Error
Permissions OWN

R210: Delete Work

URL /works/{id}
Description This web resource removes the work from the system. Redirects to the Homepage on success and the View Work page on failure.
Method DELETE
Parameter +id: integer work id
Redirects UI01 Success
R203 Error
Permissions OWN, ADM

R211: Delete Item

URL /works/{work_id}/items/{item_id}
Description This web resource removes the item from the system. Redirects to the Work page on success and the Edit Item page on failure.
Method DELETE
Parameter +work_id: integer work id
+item_id: integer item id
Redirects R203 Success
R203 Error
Permissions OWN, ADM

Module M03: Reviews and Wish list

Endpoints of Module Reviews and Wish list

  • R301: View Reviews API [/api/works/{id}/reviews]
  • R302: Add Review [/works/{work_id}/reviews]
  • R303: Edit Review [/works/{work_id}/reviews/{review_id}]
  • R304: Delete Review [/works/{work_id}/reviews/{review_id}]
  • R305: View Wish list [/users/{id}/wishlist]
  • R306: Add to Wish list [/users/{user_id}/wishlist/works/{work_id}]
  • R307: Remove from Wish list [/users/{user_id}/wishlist/works/{work_id}]

R301: View Reviews

URL /api/works/{id}/reviews
Description This web resource displays the work's reviews.
Method GET
Parameters +id: integer Work id
Response body JSON301
Permissions OWN, ADM

R302: Add Review

URL /works/{work_id}/reviews
Description This web resource adds a new review.
Method POST
Parameters +work_id: integer Work id
Request Body +user_id: integer User id
+comment: string Comment text
+rate: integer Rate
Returns 200 OK The review was successfully added.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No work with the specified primary key exists.
Permissions USR

R303: Edit Review

URL /works/{work_id}/reviews/{review_id}
Description This web resource edits a work review.
Method PUT
Parameter +work_id: integer Work id
+review_id: integer Review id
Request Body +comment: string Review text
+rate: integer Review rating
Returns 200 OK The review was successfully edited.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No work with the specified primary key exists.
Permissions USR, OWN

R304: Delete Review

URL /works/{work_id}/reviews/{review_id}
Description This web resource deletes a review.
Method DELETE
Parameters +work_id: integer Work id.
+review_id: integer Review id.
Returns 200 OK The review was successfully deleted.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No work with the specified primary key exists.
Permissions OWN, ADM

R305: View Wish list

URL /users/{id}/wishlist
Description Show user's wish list page.
Method GET
Parameter +id: integer user id
AJAX Calls R307
UI N/A
Permissions USR

R306: Add to Wish list

URL /users/{user_id}/wishlist/works/{work_id}
Description This web resource add the work to the wish list.
Method POST
Parameters +work_id: integer Work id
+user_id: integer User id
Returns 200 OK The work was successfully added to the wish list.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No work or user with the specified primary key exists.
Permissions USR

R307: Remove from Wish list

URL /users/{user_id}/wishlist/works/{work_id}
Description This web resource remove the work to the wish list.
Method DELETE
Parameters +user_id: integer Work id
+work_id: integer User id
Returns 200 OK The work was successfully removed from the wish list.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No work with the specified primary key exists.
Permissions USR, ADM

Module M04: Loans

Endpoints of Module Loans

  • R401: My Loans [/users/{id}/loans]
  • R402: Loan Item [/users/{owner_id}/loans]
  • R403: End Loan [/users/{user_id}/loans/{loan_id}/end]
  • R404: Edit Loan [/users/{user_id}/loans/{loan_id}/edit]

R401: My Loans

URL /users/{id}/loans
Description Get all my loaned items.
Method GET
Parameters +id: integer User id.
UI N/A
Permissions OWN

R402: Loan item

URL /users/{owner_id}/loans
Description Loan an item to another user.
Method POST
Parameters +owner_id: integer Owner id.
Request Body +borrower_user_id: integer User that borrows the item.
+item_id: integer Item id.
Returns 200 OK The item was successfully loaned.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No item with the specified primary key exists.
Permissions USR, OWN, ADM

R403: End loan

URL /users/{user_id}/loans/{loan_id}/end
Description This web resource ends a item loan.
Method PUT
Parameters +user_id: integer User id
+loan_id: integer Loan id
Returns 200 OK The item was successfully delivered.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No item with the specified primary key exists.
Permissions OWN, ADM

R404: Edit loan

URL /users/{user_id}/loans/{loan_id}/edit
Description This web resource edits an item loan.
Method PUT
Parameters +user_id: integer User id
+loan_id: integer Loan id
Returns 200 OK The loan was successfully updated.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No loan with the specified primary key exists.
Permissions OWN, ADM

Module M05: User Administration and Static pages

Endpoints of User Administration and Static pages

  • R501: Get users [/users]
  • R502: Suspend user [/users/{id}/suspend]
  • R503: Reinstate users [/users/{id}/reinstate]
  • R504: About [/about]
  • R505: Services [/services]
  • R506: FAQ [/faq]
  • R507: 404 [/404]

R501: Get users

URL /users
Description Get all registed users.
Method GET
UI UI15
Permissions ADM

R502: Suspend user

URL /users/{id}/suspend
Description This web resource suspends an user.
Method PUT
Parameters +id: integer User id
Returns 200 OK The user was successfully suspended.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No user with the specified primary key exists.
Permissions ADM

R503: Reinstate user

URL /users/{id}/reinstate
Description This web resource reinstates an user.
Method PUT
Parameters +id: integer User id
Returns 200 OK The user was successfully reinstated.
400 Bad Request Error. Error message is specified via a HTTP header.
404 Not Found Error. No user with the specified primary key exists.
Permissions ADM

R504: About

URL /about
Description Get about page.
Method GET
UI UI02
Permissions PUB

R505: Services

URL /services
Description Get services page.
Method GET
UI UI03
Permissions PUB

R506: FAQ

URL /faq
Description Get faq page.
Method GET
UI UI04
Permissions PUB

R507: 404

URL /404
Description Get 404 page.
Method GET
UI UI09
Permissions PUB

4. JSON/XML Types

The structure of the JSON formatted answers must be documented as illustrated below.

JSON202: Search Works: {work}[]

{
  "work": [
    {
      "id": "1",
      "title": "Rihanna - Unapologetic",
      "obs": "Good pop music album.",
      "year": "2012",
      "owner": "Joana Lima",
      "type": "MP3"
    },
    {
      "id": "15",
      "title": "Mr. Bean",
      "obs": "The best comedy movie.",
      "year": "1995",
      "owner": "Manuel Teixeira",
      "type": "DVD"
    }
  ]
}

JSON301: View reviews: {review}[]

{
  "reviews": [
    {
      "id": "5",
      "id_user": "1",
      "id_work": "1",
      "comment": "Good pop music album.",
      "rating": 4,
      "date": "2008-01-20 03:14:07"
    },
    {
      "id": "10",
      "id_user": "2",
      "id_work": "1",
      "rating": 2,
      "comment": "Bad pop music album.",
      "date": "2008-01-19 03:14:07"
    }
  ]
}

JSON403: Loan history: {loan}[]

{
  "loan": [
    {
      "user": "Rui Paulo",
      "start": "2008-01-19 03:14:07",
      "end": "2008-01-30 03:14:07"
    },
    {
      "user": "Jaime Teixeira",
      "start": "2008-01-19 03:14:07",
      "end": ""
    }
  ]
}

LBAW

[MediaLibrary]

teach/lbaw/medialib/a07.txt · Last modified: 30/03/2020 17:02 by Correia Lopes