|
1 | | -# StudentStats |
| 1 | +# StudentStats 🌐 |
2 | 2 |
|
3 | | -## What does it do? |
| 3 | +## What does it do? 📊 |
4 | 4 |
|
5 | 5 | Students from any Polish university that uses USOS as their university platform can log in through USOS to view their study statistics in an appealing graphical form. |
6 | 6 |
|
7 | | -This project leverages the usos4j library for seamless integration with the USOS platform. You can learn more about the usos4j library at the [usos4j GitHub repository](https://github.com/WMS-DEV/usos4j) |
| 7 | +This project leverages the usos4j library for seamless integration with the USOS platform. You can learn more about the usos4j library at the [usos4j GitHub repository](https://github.com/WMS-DEV/usos4j). |
8 | 8 |
|
9 | | -## Getting started |
| 9 | +Check out the deployed version here: [StudentStats Live 🌐](https://studentstats.wmsdev.pl) |
10 | 10 |
|
11 | | -- provide environment variables (see [.env-sample](/.env-sample)) |
12 | | -- provide data for supported universities in [.supported_universities.csv](/service/src/main/resources/data) (see [supported_universities-example.csv](/service/src/main/resources/data/supported_universities-example.csv)) |
13 | | - - you can find links to generate API keys at [USOS API installations page](https://apps.usos.edu.pl/developers/api/definitions/installations/) |
14 | | -- run with Docker |
| 11 | +## Getting started ⚡ |
15 | 12 |
|
16 | | -## How to authenticate through USOS |
| 13 | +- Provide environment variables (see [.env-sample](/.env-sample)) |
| 14 | +- Provide data for supported universities in [.supported_universities.csv](/service/src/main/resources/data) (see [supported_universities-example.csv](/service/src/main/resources/data/supported_universities-example.csv)) |
| 15 | + - You can find links to generate API keys at [USOS API installations page](https://apps.usos.edu.pl/developers/api/definitions/installations/) |
| 16 | +- Run with Docker ⚙️ |
17 | 17 |
|
18 | | -- `POST` request to `/auth/request-token` endpoint with `universityId` in JSON body (supported universities are listed at `/universities`) |
19 | | -- request should return `requestToken`, `tokenSecret`, and `authorizationUrl` |
20 | | -- login through `authorizationUrl`, then get redirected back to origin page with a `verifier` as URL query param (if there is no callback, `verfifier` is displayed on USOS page) |
21 | | -- `POST` request to `/auth/access-token` endpoint with `requestToken`, `tokenSecret`, `verifier`, and `universityId` in JSON body |
22 | | -- request should return `jwt` |
23 | | -- include `Authorization` Header with value: `Bearer ${jwt}` when requesting data from `/getData` |
| 18 | +## How to authenticate through USOS ✅ |
24 | 19 |
|
25 | | -### Postman configuration for easier debugging |
| 20 | +1. `POST` request to `/auth/request-token` endpoint with `universityId` in JSON body (supported universities are listed at `/universities`) |
| 21 | +2. Request should return `requestToken`, `tokenSecret`, and `authorizationUrl` |
| 22 | +3. Log in through `authorizationUrl`, then get redirected back to the origin page with a `verifier` as URL query param (if there is no callback, `verifier` is displayed on the USOS page) |
| 23 | +4. `POST` request to `/auth/access-token` endpoint with `requestToken`, `tokenSecret`, `verifier`, and `universityId` in JSON body |
| 24 | +5. Request should return `jwt` |
| 25 | +6. Include `Authorization` Header with value: `Bearer ${jwt}` when requesting data from `/getData` |
26 | 26 |
|
27 | | -You can test backend functionallity with Postman with our collection, pre-configured with endpoints and environments. All you need to do is to import [this folder](/service/postman) into Postman. |
| 27 | +## Postman configuration for easier debugging 🔧 |
| 28 | + |
| 29 | +You can test backend functionality with Postman using our collection, pre-configured with endpoints and environments. All you need to do is to import [this folder](/service/postman) into Postman. |
0 commit comments