Skip to content

Commit a459888

Browse files
clonerplusclonerplus
committed
updated document
1 parent 29622db commit a459888

File tree

2 files changed

+185
-104
lines changed

2 files changed

+185
-104
lines changed

‎GUIDE.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# University education system Rest-API
2+
3+
this project only includes the server side of the mentioned system and provides web services. In this document, the term LCRUD or its sub phrases are abbreviations respectively List, Create, Read, Update, Delete
4+
5+
#### Basic design of entities
6+
7+
![App Screenshot](imgs/entities.png)
8+
<br><br>
9+
10+
#### Description of users:
11+
12+
• We have four types of users: admin, student, instructor and staff.
13+
<br>
14+
• Users have some common information (such as username and password) and some specific information (such as student number that is specific to students).
15+
<br>
16+
• A user can be both a student and an instructor.
17+
<br><br>
18+
19+
#### Lesson description:
20+
21+
• We have a number of terms and a number of courses.
22+
<br>
23+
• In each term, each instructor can offer a number of lessons, which we call a section.
24+
<br>
25+
• Each student can register in a number of study courseSections.
26+
<br><br>
27+
28+
### Required web services
29+
30+
In most of the web services of the system we implemented authentication mechanism, which means that the client should put a suitable header in its request and the server will realize the identity by using it.
31+
<br>
32+
Tip: Search for authentication and authorization keywords along with spring.
33+
<br>
34+
35+
#### User registration
36+
37+
Anyone can register by providing username, password, name, phone number and national code. All fields are mandatory. Username, phone number and national code must be unique. If successful, the personal user will be created passively.
38+
<br>
39+
Stored users passwords in a hashed form in the database.
40+
<br>
41+
42+
#### User Authentication
43+
44+
Anyone can log in to the system by providing a username and password. If it is correct, the server must provide the necessary information to the client to put in the header in the next requests so that the server can authenticate him.
45+
<br>
46+
47+
#### Staff management
48+
49+
Admin can register another person as a staff in the system by providing the username and personnel ID, and in this case, that user will be activated.
50+
Explaining that the staff must have registered himself first and then tell the administrator the username so that he can continue the registration. Other LRUD operations must also be enabled by the administrator.
51+
52+
#### Instructor registration
53+
54+
Similar to staff registration, with the consideration that CUD operations can be performed by admin and staffs and LR operations can be performed by all users.
55+
<br>
56+
57+
#### Student registration
58+
59+
Similar to instructor registration.
60+
<br>
61+
62+
#### Term definition
63+
64+
In the form of LCRUD, LR can be done by all users and CUD can only be done by admin and staffs.
65+
<br>
66+
67+
#### Course definition
68+
69+
In the form of LCRUD, LR can be done by all users and CUD can only be done by admin and staffs.
70+
<br>
71+
72+
#### CourseSection definition
73+
74+
In the form of LCRUD, LR can be done by all users and C can only be done by the admin. UD operations can be performed by admin, staffs and also by the instructor who himself defined this courseSection. Operation D is conditional on the fact that no student is enrolled in this courseSection.
75+
<br>
76+
77+
#### Registration in the courseSection
78+
79+
It is done by the student and by presenting the class ID.
80+
<br>
81+
82+
#### Get the list of class students
83+
84+
It can be done by the instructor, administrator and staff in such a way that the list of registered students will be presented after receiving the ID of the courseSection. For each student, student ID, name, student number and grade are provided.
85+
<br>
86+
87+
#### Grading students
88+
89+
It can be done by the instructor, in this way, by receiving the class ID, student ID and grade, the grade is registered.
90+
<br>
91+
Grading the list of students, in such a way that a courseSection ID and a list of student IDs and grades are received.
92+
<br>
93+
94+
#### View term grades
95+
96+
It can be done by the student, in such a way that upon receiving the term ID, the grade point average of the term as well as the list of student courseSections in that term along with each grade will be provided. For each courseSection, courseSection ID, course name, number of units, instructor's name and grade should be provided.
97+
<br>
98+
99+
#### View academic summary
100+
101+
It can be done by the student, in such a way that it provides the total grade point average of the student as well as the list of terms along with the grade point average of each term. For each term, the term ID, term title and term average should be provided.
102+
<br>
103+
104+
### Automated test
105+
106+
• Write a unit test to calculate the student's GPA in one term. • Write an integration test for this scenario: the instructor defines a courseSection, the student enrolls in that courseSection,
107+
<br>
108+
The instructor grades the student, the student sees the term grades correctly (hint: you can use MockMvc if you wish)
109+
110+
## API Reference
111+
112+
after building dependencies and running these are some sample endpoints to test
113+
114+
#### Get all users:
115+
116+
```bash
117+
curl -X GET -w " %{http_code}\n" "http://127.0.0.1:8080/all-users"
118+
```
119+
120+
| Parameter | Type | Description |
121+
| :------------------ | :---- | :----------------------- |
122+
| `list of all users` | `GET` | No authentication needed |
123+
124+
#### Register a new custom user:
125+
126+
```bash
127+
curl -X POST -H "Content-Type: application/json" -d @/absolute/path/to/costumUser.json -w " %{http_code}\n" "http://127.0.0.1:8080/register"
128+
```
129+
130+
| Parameter | Type | Description |
131+
| :---------------------------------- | :----- | :----------------------- |
132+
| `customUser json registration file` | `POST` | No authentication needed |
133+
134+
#### Register a new custom user:
135+
136+
```bash
137+
curl -X POST -H "Content-Type: application/json" -d @/absolute/path/to/userAuth.json -w " %{http_code}\n" "http://127.0.0.1:8080/authenticate"
138+
```
139+
140+
| Parameter | Type | Description |
141+
| :------------------------------------ | :----- | :----------------------------------------- |
142+
| `customUser json authentication file` | `POST` | **Required** correct username and password |
143+
144+
| Parameter | Type | Description |
145+
| :--------------------- | :---- | :----------------------------------------- |
146+
| `authentication token` | `GET` | **Required** correct username and password |
147+
148+
#### Register a new custom user:
149+
150+
```bash
151+
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d @/absolute/path/to/instructor.json -w " %{http_code}\n" "http://127.0.0.1:8080/authorize/instructor?username=ali"
152+
```
153+
154+
| Parameter | Type | Description |
155+
| :------------------------------------ | :----- | :----------------------------------------- |
156+
| `customUser json authentication file` | `POST` | **Required** correct username and password |

‎ReadMe.md

Lines changed: 29 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,47 @@
1-
# University education system Rest-API
2-
this project only includes the server side of the mentioned system and provides web services. In this document, the term LCRUD or its sub phrases are abbreviations respectively List, Create, Read, Update, Delete
3-
4-
#### Basic design of entities
5-
![App Screenshot](imgs/entities.png)
6-
<br><br>
7-
#### Description of users:
8-
• We have four types of users: admin, student, instructor and staff.
9-
<br>
10-
• Users have some common information (such as username and password) and some specific information (such as student number that is specific to students).
11-
<br>
12-
• A user can be both a student and an instructor.
13-
<br><br>
14-
#### Lesson description:
15-
• We have a number of terms and a number of courses.
16-
<br>
17-
• In each term, each instructor can offer a number of lessons, which we call a section.
18-
<br>
19-
• Each student can register in a number of study courseSections.
20-
<br><br>
21-
### Required web services
22-
In most of the web services of the system we implemented authentication mechanism, which means that the client should put a suitable header in its request and the server will realize the identity by using it.
23-
<br>
24-
Tip: Search for authentication and authorization keywords along with spring.
25-
<br>
26-
#### User registration
27-
Anyone can register by providing username, password, name, phone number and national code. All fields are mandatory. Username, phone number and national code must be unique. If successful, the personal user will be created passively.
28-
<br>
29-
Stored users passwords in a hashed form in the database.
30-
<br>
31-
#### User Authentication
32-
Anyone can log in to the system by providing a username and password. If it is correct, the server must provide the necessary information to the client to put in the header in the next requests so that the server can authenticate him.
33-
<br>
34-
#### Staff management
35-
Admin can register another person as a staff in the system by providing the username and personnel ID, and in this case, that user will be activated.
36-
Explaining that the staff must have registered himself first and then tell the administrator the username so that he can continue the registration. Other LRUD operations must also be enabled by the administrator.
37-
#### Instructor registration
38-
Similar to staff registration, with the consideration that CUD operations can be performed by admin and staffs and LR operations can be performed by all users.
39-
<br>
40-
#### Student registration
41-
Similar to instructor registration.
42-
<br>
43-
#### Term definition
44-
In the form of LCRUD, LR can be done by all users and CUD can only be done by admin and staffs.
45-
<br>
46-
#### Course definition
47-
In the form of LCRUD, LR can be done by all users and CUD can only be done by admin and staffs.
48-
<br>
49-
#### CourseSection definition
50-
In the form of LCRUD, LR can be done by all users and C can only be done by the admin. UD operations can be performed by admin, staffs and also by the instructor who himself defined this courseSection. Operation D is conditional on the fact that no student is enrolled in this courseSection.
51-
<br>
52-
#### Registration in the courseSection
53-
It is done by the student and by presenting the class ID.
54-
<br>
55-
#### Get the list of class students
56-
It can be done by the instructor, administrator and staff in such a way that the list of registered students will be presented after receiving the ID of the courseSection. For each student, student ID, name, student number and grade are provided.
57-
<br>
58-
#### Grading students
59-
It can be done by the instructor, in this way, by receiving the class ID, student ID and grade, the grade is registered.
60-
<br>
61-
Grading the list of students, in such a way that a courseSection ID and a list of student IDs and grades are received.
62-
<br>
63-
#### View term grades
64-
It can be done by the student, in such a way that upon receiving the term ID, the grade point average of the term as well as the list of student courseSections in that term along with each grade will be provided. For each courseSection, courseSection ID, course name, number of units, instructor's name and grade should be provided.
65-
<br>
66-
#### View academic summary
67-
It can be done by the student, in such a way that it provides the total grade point average of the student as well as the list of terms along with the grade point average of each term. For each term, the term ID, term title and term average should be provided.
68-
<br>
69-
### Automated test
70-
• Write a unit test to calculate the student's GPA in one term. • Write an integration test for this scenario: the instructor defines a courseSection, the student enrolls in that courseSection,
71-
<br>
72-
The instructor grades the student, the student sees the term grades correctly (hint: you can use MockMvc if you wish)
73-
## API Reference
74-
after building dependencies and running these are some sample endpoints to test
75-
76-
#### Get all users:
1+
# spring-rest-api-with-jwt
772

78-
```bash
79-
curl -X GET -w " %{http_code}\n" "http://127.0.0.1:8080/all-users"
80-
```
3+
![build](https://github.com/hantsy/spring-webmvc-jwt-sample/workflows/build/badge.svg)
814

82-
| Parameter | Type | Description |
83-
|:--------------------|:------|:-------------------------|
84-
| `list of all users` | `GET` | No authentication needed |
5+
## What is this?
856

86-
#### Register a new custom user:
7+
This is a sample project demos how to use JWT token based authentication to protect the RESTful APIs in a Spring WebMVC application.
878

88-
```bash
89-
curl -X POST -H "Content-Type: application/json" -d @/absolute/path/to/costumUser.json -w " %{http_code}\n" "http://127.0.0.1:8080/register"
90-
```
9+
## Guide
10+
11+
Check the [full GUIDE](./GUIDE.md) to get the detailed explanation of the example codes.
12+
13+
## Prerequisites
9114

92-
| Parameter | Type | Description |
93-
|:------------------------------------|:-------|:---------------------------------|
94-
| `customUser json registration file` | `POST` | No authentication needed |
15+
Make sure you have installed the following software.
9516

96-
#### Register a new custom user:
17+
- Java 17
18+
- Apache Maven 3.9.x
19+
20+
## Build
21+
22+
Clone the source codes from Github.
9723

9824
```bash
99-
curl -X POST -H "Content-Type: application/json" -d @/absolute/path/to/userAuth.json -w " %{http_code}\n" "http://127.0.0.1:8080/authenticate"
25+
git clone https://github.com/clonerplus/rest-api
10026
```
10127

102-
| Parameter | Type | Description |
103-
|:--------------------------------------|:-------|:-------------------------------------------|
104-
| `customUser json authentication file` | `POST` | **Required** correct username and password |
105-
106-
| Parameter | Type | Description |
107-
|:-----------------------|:------|:-------------------------------------------|
108-
| `authentication token` | `GET` | **Required** correct username and password |
109-
#### Register a new custom user:
28+
Open a terminal, and switch to the root folder of the project, and run the following command to build the whole project.
11029

11130
```bash
112-
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -d @/absolute/path/to/instructor.json -w " %{http_code}\n" "http://127.0.0.1:8080/authorize/instructor?username=ali"
31+
mvn clean install // build the project
11332
```
11433

115-
| Parameter | Type | Description |
116-
|:--------------------------------------|:-------|:-------------------------------------------|
117-
| `customUser json authentication file` | `POST` | **Required** correct username and password |
34+
Run the application.
35+
36+
```bash
37+
mvn spring-boot:run
38+
// or from command line after building
39+
java -jar target/xxx.jar
40+
```
11841

42+
## Contribution
11943

120-
**If you found this project helpful, consider giving it a star ⭐️ for others to find! ❤️**
44+
Any suggestions are welcome, filing an issue or submitting a PR is also highly recommended.
45+
**If you found this project helpful, consider giving it a star ⭐️ for others to find! ❤️**
12146

12247
[![GitHub stars](https://img.shields.io/github/stars/clonerplus/rest-api.svg?style=social&label=Star)](https://github.com/clonerplus/rest-api)

0 commit comments

Comments
 (0)