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.
- Complete 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.
- Implement a second service that utilizes 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 and follows ROA architecture. In addition, it is recommended that the API utilizes hypermedia formats. Students will also design, implement and document a client application that uses that Web API functionality, and an additional service component that interacts with the API server and the client.
Therefore, the final deliverable can include up to three fully functional pieces of software: the Web API, the client application, and an auxiliary service. 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. The auxiliary component is more of an automated process that performs some calculations/filtering/compiling etc on the API data that should not be done on the API server itself.
Project work implementation and documentation in short¶
Software of the project must be stored in a GIT repository. Students can choose among Github and Gitlab. 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 Gitlabor Github repo. Please, note that the documentation must be written in the wiki. The wiki with the skeleton of the documentation can be found in the gitlab project wiki or github project wiki
The documentation must be written in English or Finnish.
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. Only the web API is needed to complete the course, but not implementing the client will lead into a low grade (2 at most). Exercises 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 deadlines 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. This option is only available for groups of 3 or 4 students.
- 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. Groups choosing the final deliverable option must have a mid-term meeting after deadline 3 or 4.
Group members and registration¶
Students must form groups of 3-4 members.
Each group selects its own topic and register it using the registration return box on this page. Check the return box for instructions when it is available.
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: Github project template
- Gitlab: Gitlab project template
Remember that the documentation must be uploaded to the Wiki of the project:
- Gitlab wiki: Gitlab Wiki template
- Github wiki: Github Wiki template
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.
Instructions. What to do in this section (heading)?
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. Detailed evaluation criteria for each section can be found in the return box of that section. Check the Assessment Criteria available in each return box
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.
- Read carefully the assessment criteria for each one of the sections in the return box. It will give you a clear idea of what we expect from each deadline. By reading carefully the assessment criteria, you will avoid unfortunate situations in which you write / implement something that is not exactly what was expected.
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) and possibly for the auxiliary service. 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. The Flask API project layout from Exercise 3 provides a recommended structured for Python. We also provide a full example project.
- 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¶
Student groups will have chances to meet with the course staff during the project. During those meetings the teachers ask some questions to clarify certain concepts and give some recommendations. The meeting reservation calendar will be in Lovelace.
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, 4 and one final meeting to present the project results. Most meetings are 30 minutes. Exceptions: first meeting is 20 minutes; final meeting is between 40 and 60 minutes.
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
Minimum requirements and constraints¶
Students can use any programming language both for the RESTful API and for the client application. BUT:
- We can only give support 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.
In order to pass the course students must deliver:
- The project report with all sections except 5
- A working version of the Web API.
- Check minimum requirements for the RESTful API in the following subsections
- Enough exercises to fulfill the points requirement
In order to get a good grade (3 or more) students must deliver:
- The full project report
- A working version of the web API and the client
- Check minimum requirements for the RESTful API and the client in the following subsections.
In addition, students can implement a third piece of software called "auxiliary service" to improve their grade further. Note that it is possible to get a five without this component, it is just very, very hard.
RESTful API¶
- Design and implement at least 5 resources. You can design and implement more resources if you want. 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 3
- Students must provide software to test:
- The RESTful API (functional testing)
- We recommend to use Hypermedia format (e.g. Mason, 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. Mason) will not be able to get full points in all the sections.
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.
Auxiliary Service¶
- Communicate with the API and the client
- Performs some operations that should be separated from the API server
- Cannot be human-driven - a human can message this service through an interface in the client, but the service itself is not directly controlled by a human.
- This service does not need to use REST API. Any other approach (event-driven / RPC...) can be used. More info of possibilties in Exercise 4.
Project Schedule¶
- 2024-01-19 23:59 - Group registration
- 2024-01-26 23:59 - Project Plan
- 2024-02-09 23:59 - Database
- 2024-03-01 23:59 - API Basic Implementation
- 2024-03-22 23:59 - API Documentation and Hypermedia
- 2024-04-26 23:59 - API consumption (Client + Auxiiliary service)
- 2024-05-06 23:59 - Final deliverable including Project Reflection and Feedback
Evaluation criteria¶
Majority of the grade is based on your project and the project report. Exercises contribute a small portion of the grade. Project is graded in terms of both quality of the code and documentation, and also the number of implemented features. The number of implemented components is also a major factor in grading. You should choose which components to implement based on your goal. Here are rough requirements for each grade:
- Grade 1::
- Complete first two exercises fully
- Implement a functional API server with basic features
- Document your API
- Write the analysis and reflection section
- Attend meeting with course staff, writing meeting notes and keep track of tasks and hours for each member of the team.
- Grade 2:
- Complete first three exercises fully
- Implement an API server with most graded features
- Document your API
- High quality code base and documentation
- Write the analysis and reflection section
- Attend meeting with course staff, writing meeting notes and keep track of tasks and hours for each member of the team.
- Grade 3:
- Complete all exercises
- Implement a functional API server and a functional client for it
- Document your API
- Attend meeting with course staff, writing meeting notes and keep track of tasks and hours for each member of the team.
- Grade 4:
- Complete all exercises
- Implement an API server with most graded features
- Use hypermedia
- Make your client take full advantage of hypermedia
- Write the analysis and reflection section
- Attend meeting with course staff, writing meeting notes and keep track of tasks and hours for each member of the team.
- Document your API
- Grade 5:
- Same as 4, but also implement the third component
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 | 5 |
Database design and implementation | D2 | 5 |
RESTful Web Service API implementation | D3 | 21 |
RESTful Web Service API documentation | D4 | 18 |
API consumption (client design and implementation + auxiliary service | D5 | 26 |
Analysis and reflection | D6 | 5 |
Project manangement and participation | - | 4 |
Exercises | - | 16 |
Table 1. Evaluation.
Exercise Assessment¶
Each exercise is assessed automaticatlly by Lovelace. Each exercise will provide a maximum of 4 points. If you miss the deadline for the exercise, you still need to deliver the exercise to pass the course, but your grade will be reduced in half (so you can get a maximum of 2 points)
Final Grade¶
The final grade is obtained by adding up the grade for each one of the topics. Students must get at least the 37 points out of 100 to pass the course.
Point (out of 100) | Final Grade |
<= 36 | 0 |
37 - 45 | 1 |
46- 60 | 2 |
61 - 72 | 3 |
73 -87 | 4 |
>= 88 | 5 |
Figure 2. Final grade
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.
Please bear in mind that the focus of the course has slightly shifted, and some of these topic ideas may not be as suitable for the current implementation of the course.
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.
2020¶
- Web App Store
- Expense Tracker & Budget Planning
- World betterers
- Car installment calculator
- Game Score API
- Florida Man Generator
- Booking Management System
- Guild Coffee
- RaceTime Tracker
- GameScoresAPI
- Smart Data API
- Library Circulation System
- OJObs
- Booking Managment System
- BudgetTracker
- weathertalk
- PandaBoard
- Web Trivia
- Journey Diary
- BookingManagementSystem
- Events API
- Bike component usage hour tracking
- Training diary for running
- Port Call Information Sharing
- Moovie Wish listener
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
Disclaimer¶
Information contained in this document could change during the course. Any significant change to this document will be announced using Discord and/or mail through Lovelace.
Questions?¶
For further questions or clarifications:
- Contact us through the course mail: pwp-course@lists.oulu.fi
- Use the course Discord. You should have received an email with the invitation. Otherwise, contact the group staff.
Anna palautetta
Kommentteja ohjeista?