In database terminology primary key refers to the column in a table that's intended to be the primary way of identifying rows. Each table must have exactly one, and it needs to be unique. This is usually some kind of a unique identifier associated with objects presented by the table, or if such an identifier doesn't exist simply a running ID number (which is incremented automatically).
Project implementation¶
During this project work the students:
- Select a topic for the Web API.
- Write a textual description about the Web API.
- Attend the exercises where they learn how to use different software tools, frameworks and libraries that they need for their project work.
- Create a database to store persistent data for the RESTful API.
- Implement the functionality of the Web API.
- Create a client application that allows a user to access the API functionality by means of a GUI (or using command line).
- Write a project report which documents in detail the work done using a template.
- Modify the report and/or files according to the comments received from the course staff.
- Present the progress at meetings with the course staff; at least twice during the course.
Requirements overview¶
General requirements¶
During this course, the students have to design, document, implement and test a Web API, that meets REST principles, follows ROA architecture. In addition, it is recommended that the API utilizes hypermedia formats. Students must also design, implement and document a client application that uses that Web API functionality.
Therefore, the final deliverable should include two fully functional pieces of software: the Web API and the client application. The client application must be able to send HTTP requests to retrieve or modify resources in the server. The Web API must process those requests and generate adequate HTTP responses. The Web API must be able to store persistent data (i.e. must contain a functional database). Figure 1 shows the general architecture of the system.
'
Project work implementation and documentation in short¶
Software of the project must be stored in a GIT repository. Students can choose among Github, Gitlab or Bitbucket. The Project Work Report must be written in a Wiki associated to the previous GIT repository. The repo structure as well as the Project Work Report section are provided by the course staff. More information in the GIT repo setup section.
GIT repo and Project Report template must be forked from the course Gitlab repo or Github repo
The documentation must be written in English.
The students are free to choose the development environment and programming language they prefer. However, the course staff only provide support for the programming languages and the web frameworks and libraries utilized during the exercises. Students who choose a different programming language or framework must configure the development environment and tools by themselves. Furthermore, they must deploy the Web API in a public server accessible by the course staff, with clear information on how to test their API.
Assessment in short¶
The final grade of the course depends on the quality and correctness of both the Project Work Report and the software implementation. Both, the Web API and the client application must implement basic functionality in order to pass the course. Exercises and meeting with the course staff will have also some impact on the final grade. More detailed grading information can be found from the Evaluation criteria section of this documentation.
In addition, there is a minimum set of requirements that the projects must meet in order to pass this course. They are specified in section "Minimum requirements and constraints" of this document.
Important note concerning plagiarism: Course staff will not tolerate plagiarism. If the course staff detects plagiarism the students will automatically fail the course. When students include text, JSON/javascript fragments, code ... written by somebody else, they must indicate clearly the origin. It must be clear what is the student's own work and what is work created by others. The project work must contain mainly material generated by students themselves.
Workflow¶
Students may select among two different workflows:
- 6 different deliverables: Students should deliver different sections of project work report as well as the software implementation in different deadlines. After deadline 1-4 students will have a meeting with the course staff. The staff will provide feedback to improve the project work. Students should present the final version of the project in a final meeting. Students need to attend to the exercise sessions.
- 1 final deliverable: Students must deliver both projects work report as well as the software implementation by the final deadline. Exercises must also be delivered by the final deadline. Students [[#meetings-with-the-staff|]meet twice with the course staff]: one in the middle of the course and one at the end of the course to present the final version of the project.
Group members and registration¶
Students must form groups of 3 members. We will consider other composition for groups case by case if students give justified reasons.
Each group selects its own topic and register it using the Topic Registration form in Programmable Web Project Moodle site. In the form, students must fill in:
- Topic
- Name, surname and email of team members
- Link to GIT repo with documentation.
Setting up GIT project¶
All your files and your Project Report must be uploaded to a GIT hosting service. We recommend either Github or Gitlab.
We have created a demo project that you must fork into your own account. We have the demo project in GitHub and GitLab. You can choose the best option for you.
- Github: https://github.com/programmable-web-project-unioulu/PWP
- Gitlab: https://gitlab.com/programmable-web-project-/pwp-
Only one member of the team should do the forking. The rest of team members must clone the project in their own computers.
In order to setup your environment, please, follow the instructions provided in the following tutorial: Setting up the project work environment in GIT
You can now edit your Project Work Report either using the Web interface or using your local computer and pushing the changes.
Writing the report¶
For each section you need to complete the corresponding part of the Project Work Report in your Wiki Project. At the beginning of each page you have a short summary of what you should do during that this deliverable. After each section (heading) you have instructions on what to do in that section. Furthermore, you have detailed instructions on how are we going to evaluate that section. In the instructions, we use the following symbols:
Instructions. What to do in this section (heading)?
Detailed evaluation instructions
The pencil means that you need to write your own text in this section.
The computer means that for this section you do not need to write any text but implement software
You can edit the document using the Web editor of the online platform. In addition, you can edit it from the local version of the repository in your own computer. If you use the GIT repo you need to follow the
Markdown
syntax. You can find a small tutorial in the following link. Do not forget to {{commit}} and {{push}} after you have edited the document. Some additional recommendations:
- Figures and tables: When possible try to include a caption for each Figure and Table. All your local images should be stored in the
uploads
folder. If you use the web interface to edit the files, this will be done automatically. - Attachments: You can attach any kind of files to the report but it must be added as a link. You can use the
uploads
folder in order to save any file. You can make a link to that file in the documentation. - Report changes: It is highly recommended to write a short sentence explaining what you have changed in the report after each update. You can use either the commit message if you are editing locally or the Edit message or Commit message box if you are in the web editor.
- Inserting code: If you need to insert code use always the markdown syntax highlighting, so the code is clearly different from the text.
It is important to note that the documentation required in this course exceeds the documentation that you normally needs to provide when implementing a Web API / Client in "real life" (e.g. in industry). However, we require that extensive documentation to be totally sure that you understand the main concepts taught during the course.
Writing the code¶
Students are free to choose the structure of your software repo. It is mandatory that the root of the repo includes the
README.md
file with clear instructions on how to setup your environment, populate the database, run your Web API and your client, run your test scripts and any other instructions that you consider relevant for us to test your Web API and client. If you are using python it is recommended that you use the file requirements.txt with all your libraries.In addition, you must include the meetings.md
file in which you must write your meeting notes.You can create a new repository for the client (for instance, if the client is developed in a non-web platform such as Python or Android). In this case, you must still keep the Project Work Report in Wiki of the original repository. Do not create the Project Work Report in two different repositories
A recommended structure for your repo is shown in Figure 2. You will have more information on how to structure your project in the one section of the exercises:
- src or app_name: source code of your application. Give an adequate name.
- lib: external libraries
- tests: sources and executables for the tests
- db: sql dumps of the database (and .db files in case of sqlite)
- scripts needed to run and setup the applications
- README.md file with clear instructions on how to setup, run and test your Web API and your client.
'
When you commit a new software version to the repository it is mandatory that you write a short description of the changes that you have done in the code.
IMPORTANT: When you pull the final version of your code for a given deadline, tag this commit using the git tag command. The tag name should be the name of the deliverable: deliverable1, deliverable2, deliverable3...
Meetings with the staff¶
Each group has to meet at least twice with the course staff to present the current status of the project work. During those meetings the assistants ask some questions to clarify certain concepts and give some recommendations.
In the case of groups who chose the final deadline option students should have one intermediate meeting and one final meeting to present the project results.
In the case of groups who chose intermediate deadlines students should have a meeting after deadline 1, 2, 3 and 4 and one final meeting to present the project results.
After each meeting students should write meeting notes and upload them to their GIT repo. The meeting notes must include a summary of what were discussed during the meeting and a set of action points agreed with the assistant
The time reserved for each meeting is ~30 minutes. Instructions to book a meeting will be announced later, but it will done very likely through Moodle.
Exercises¶
There are 4 exercise materials. In those exercises, we present to the students some software tools, frameworks and libraries that are going to be useful for their project work. Exercises will contribute 16% of the course grade. You only receive points for exercises that have passed the automatic tests successfully.
Attendance to the exercises (except for those taking the final deliverable option) is mandatory. Students will have a grade penalization if they do not attend to the exercises. If a student has a justified reason and cannot attend to an exercise session they must inform the course staff beforehand. Exercises must be delivered before the deadline announced once the exercise is published.
All students need to deliver the exercises finished in Lovelace. However, we accept (and encourage) collaborative work between group members.
Exercises topics are:
- Exercise 0: Project Work Presentation. Introduction to GIT.
- Exercise 1. Introduction to Web Development.
- Exercise 2. API design.
- Exercise 2. Implementing REST APIs with Flask.
- Exercise 4. Implementing Hypermedia client.
Minimum requirements and constraints¶
Students can use any programming language both for the RESTful API and for the client application. BUT:
- We give support only for the languages and frameworks provided in the exercises.
- If students choose a different language or platform for the server they NEED TO SET UP A SERVER SO WE CAN TEST THEIR RESTful API. For the client, students should present a demo during a meeting to any of the course staff.
The minimum requirements to pass the course are:
- The project report with all required sections
- A working version of the Web API and the client application.
RESTful API¶
- Design and implement at least 5 resources. You can design and implement more resources if you want (better grade). You can even not implement all the resources you have in your design (minimum is 5).
- Each HTTP method (GET,PUT/PATCH, POST and DELETE) must be used at least twice in the uniform interface (PATCH is not mandatory). This does not mean that all the methods GET/PUT/POST/DELETE must be used in one single resource.
- The RESTful API must be documented using any of the tools presented in Exercise 2 and 3 (e.g. Apiary, RAML, OpenAPI)
- Students must provide software to test:
- The database models(unit testing)
- The RESTful API (functional testing)
- We recommend to use Hypermedia format (e.g. HAL, Siren, UBER, Collection+Json) for the resource representations. We also accept the popular CRUD approach (that is using plain json or XML as resource representation). Still Connectedness is a ROA requirement, hence it is needed that there are links or connections among resources.
- Students who do not use hypermedia formats (e.g. HAL, UBER) will not be able to get full points in all the sections. In total they will lose 8 points (out of 100).
Client application¶
- Use at least 3 resources of the RESTful API.
- Implement a GUI or a command line tool. You can implement non-human driven clients also, but first you must explain your ideas to one member of the course staff.
- If you use HTML, it is not allowed to generate the code dynamically in the server.
- You must use Javascript asynchronous requests.
- Use all the methods of the Uniform interface at least once.
Evaluation criteria¶
The final grade of the course is mainly based in the quality of the project work. Other aspects, such as the performance in the lab exercises, active participation during the course (asking questions, using the chat and the forum...) and the meetings with the assistants are also taken into consideration. We emphasize quality vs quantity: that is, it is more important that you have a small API (small number of resources) which has a proper design following RESTful principles, with adequate documentation and tests that covers your whole application than implementing an application which contains a large amount of resources but badly documented and tested.
In general, groups who do all the exercises, agree a meeting with the assistant and CAREFULLY follow all the instructions for the project report, get a final grade of at least '3'. Usually, all members of a group get the same grade. However, if the course staff considers that the work performed by the students is not balanced (that is, one of the students has worked much more than other members of the group) the final grade could be different. Students fail the course automatically if plagiarism is detected in any of the deliverables.
When we assess the report, we take into consideration its quality and its conformance with the specifications provided in the project report. Evaluation criteria for each section is provided in the Project Work Report.
Table 1 summarizes how the course is evaluated. Table 2 shows which will be your final grade (0 to 5) based on the number of points you got during the course (out of 100).
Project Work Topic | Deadlines | Number of points (out of 100) [*] |
RESTful API description | D1 | 7.5 |
Database design and implementation | D2 | 9 |
RESTful Web Service API design | D3 | 25 |
RESTful Web Service API implementation | D4 | 18 |
Client design and implementation | D5 | 15 |
Analysis and reflection | D6 | 4.5 |
Project management | - | 5 |
Exercises | - | 16 |
Table 1. Evaluation.
Point (out of 100) | Final Grade |
< 51 | 0 |
51 - 60 | 1 |
61- 70 | 2 |
71 - 80 | 3 |
81 -90 | 4 |
> 90 | 5 |
Table 2. Final Grade.
The final grade is obtained by adding up the grade for each one of the topics. Students must get at least the 51 points out of 100 to pass the course. If you miss a deadline, you lose the corresponding points.
Each exercise (Exercise 1 to Exercise 4) will be evaluated from 0 to 4. We will consider the participation during the exercise session and the correctness of the exercise. A student cannot pass the course till Exercise 1, 2, 3 and 4 are delivered.
Extra work might increase your final grade. At maximum you can earn 15 points out of 100 by doing extra work. Extra work points count only if students meet the pass criteria (at least 60 points from table 1) .
Topics examples¶
We always recommend that you choose a project that might be useful for you in the future. Or at least, to implement a project related to some of your hobbies. For instance, in the past, we have had several groups of students interested in frisbee golf. We have had several projects related to this topic: from a system to track the score in a game to another system to store the position of different tracks and difficulty of each one of them. Other teams has implemented some software that would help in the management of their guilds: for instance to track the borrowed material to the guild members.
Here is a list of selected past projects. Please, note that many of those projects had very reduced functionality, but they were enough to complete the course.
2019¶
- Party Gallup Machine
- Gymlog App
- Sensor Data API
- Resource exchange portal
- Don't Starve - Meal planner API
- FoodPoint
- Team Sports
- Image hosting service
- Movie API
- Survey PWP
- Limping data of patients
- MapPoints
- Music API
- Smartlight controller
- Player API
- Kyykka-Data-API
- Dashboard API
- Time Tracker
- Remotely controllable network scanner & result manipulator on single-board computer Linux system
- Soothsayer
- Ebin.Chat
- Crypto trading API
- Workout Tracker
- Dependency Mapping API
- Chess Puzzles app
- Advance web blog
2018¶
- Online music store
- Event magement
- Chess Community Server
- Hunting Card Exam Simulator
- Wagemanager3k
- IoT server
- Goals Tracking sytem.
- Flight booking system
- Fysio Api
- Tutoring Management System
- Finnish Language Tutor
- Restaurant Management System
- Project Recruiting System
- Vox Populi: a platform to voice your ideas
- Online library system
- Fitness App
- Restaurant Reservation Service
- Healthcare management system
- FabLab Machines Reservation
- Lost and found service
- Criticism platform
- Movie reservation system
- Wallet Service
- Currency monitoring
- IoT Device Manager
- Battleships
- Bookstore
2017¶
- Event marketing
- Music repository
- Calendar REST API
- HR management System
- Cash register system
- Money Manager
- Book checkout system
- Message Board
- Blood Alert - A social Campaign application for blood donation and blood banking
- Room resevation API for local library
- Medicine Check
- Exercise monitoring system
- University course review system
- Share it
- Minimal blogging web application
- Movie Database
- Device Tracker
- Paste bin clone
Extra Work¶
Students can do some extra work to improve the final grade. Documentation related to the extra work must be included in the final version of the report. Before starting any extra work task, students should explain their plans to the course assistants, so they can evaluate if it can be considered as extra work. Extra work must be presented to the assistants when it is finished, so students must agree a meeting with them. Examples of tasks that can be considered as extra work are:
- Implement the client application using the RESTful API of another student group.
- Peer-review: You provide feedback to other student's API design.
- Public presentation of student's work to other researchers/partners.
- Implement two different RESTful APIs. The client application uses both APIs. Another option is that one RESTful API call each other.
- Make use of existing RESTful APIs in your clients.
- Do exhaustive unit testing.
- Use RESTful advanced features: authentication, permission caching, transactions…
- Support multiple formats in the entity response.
- Implement a client application for a mobile device.
- Implement two different versions of the database (relational / non relational)
Students should only consider the Extra Work when they have finalized the basic course requirements. That means, for example, that students should not consider authentication while designing the RESTful API.
Deadlines¶
FINAL DEADLINE FOR ALL STUDENTS TO DELIVER THE PROJECT WORK AND ALL THE EXERCISES IS 07.05.2019
In addition, if students opted for the intermediate deadlines option, they have five intermediate deadlines in addition to the final deadline. Before each deadline, the students must complete the corresponding sections of the project report and upload the code to the GIT repository. After each deadline, the course staff will meet the students and provide individual feedback, suggesting how the project work can be improved. Students must write some meeting minutes, upload it to the GIT repository and modify the project work according to this feedback. The modifications made during the course will be considered for the final grade. Extra work material (see "Extra work" section ) must be delivered with the final deliverable.
NOTE: Students will not receive feedback from deliverable 5. If a group considers that they need such feedback, they should contact the course assistants directly and agree a meeting with them.
Deadline schedule is as follows:
- Deadline 0 :Topic registration using Moodle registration form (Topic registration) (26th Jan)
- Deadline 1: RESTful API introduction (02.02.2020)
- Deadline 2: Database design and implementation (16.02.2020)
- Deadline 3: RESTful API Design (08.03.2020)
- Deadline 4: RESTful API implementation (05.04.2020)
- Deadline 5: Client design and implementation (26.04.2020)
- Deadline 6 : Final Deliverable (07.05.2020). FOR ALL STUDENTS
Disclaimer¶
Information contained in this document could change during the course. Any significant change to this document will be announced using Moodle and/or mail through Weboodi.
Questions?¶
For further questions or clarifications:
- Contact us through the course mail: pwp-course@lists.oulu.fi
- Use the course Mattermost channel. You should receive an invitation to join the channel during the first two weeks of the course if you have successfully registered to weboodi.
- Drop to the teacher's (TS354) or assistant's (TS354, TS373) . It is advisable to agree a meeting in advance.
Anna palautetta
Kommentteja ohjeista?