Skip to content

Commit a4ad224

Browse files
AndreCostaaaAndreCostaaa
authored
Added documentation (#10)
* created documentation and fixed image in docker compose
1 parent 2106992 commit a4ad224

File tree

3 files changed

+218
-1
lines changed

3 files changed

+218
-1
lines changed

‎compose.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
services:
22
api:
3-
image: andrecosta222/gaps-notifier-api
3+
image: ghcr.io/andrecostaaa/gaps-notifier-api:latest
44
restart: always
55
build:
66
context: .

‎media/schema.png‎

76.4 KB
Loading

‎readme.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,218 @@
11
# Gaps Notifier API
2+
3+
## Introduction
4+
5+
- Gaps Notifier provides notifications to multiple users around [gaps](https://gaps.heig-vd.ch/)
6+
7+
## [Gaps](https://gaps.heig-vd.ch/)
8+
9+
- Gaps is an Academical Planning System
10+
11+
## Gaps Notifier
12+
13+
- This api is meant to notify users when events happen in gaps
14+
15+
- This api is run by users for users, which means that it can't notify anyone if no data is fed into it
16+
17+
- To automatize this data feeding, the [gaps-cli](https://github.com/heig-lherman/gaps-cli) or the [gaps-scraper](https://github.com/AndreCostaaa/gaps-scraper) can be used
18+
19+
![](./media/schema.png)
20+
_Main communication schema_
21+
22+
## Communication Sequence
23+
24+
### New Event
25+
26+
1. A new event is detected
27+
2. A POST request is done to the REST API
28+
3. The subscribers to this particular event are notified through webhooks
29+
30+
## Discord
31+
32+
- Integration with discord is very easily done since the gaps-notifier-api uses webhooks to notify users of events. Check this stackoverflow [thread](https://stackoverflow.com/questions/75305136/how-to-create-a-function-to-send-messages)
33+
34+
## Important - Usage Recommendation
35+
36+
- Since this application relies on information input from users to be useful, we highly recommend using the already hosted instance. This allows you to benefit from the collective contributions of all users, enhancing the utility and value of the application.
37+
38+
## API
39+
40+
- This application is currently being hosted by [Lutonite](https://github.com/Lutonite).
41+
42+
- If you wish to use it, please write me or [Lutonite](https://github.com/Lutonite) an email and we'll gladly create a user for you.
43+
44+
#### Retrieving an access token
45+
46+
<details>
47+
<summary><code>POST</code> <code><b>/api/token</b></code> <code>(Retrieves an access token)</code></summary>
48+
49+
##### Parameters
50+
51+
> | name | type | data type | description |
52+
> | ---- | -------- | ----------- | ----------------------- |
53+
> | None | required | object JSON | `{ user_id: <user_id>}` |
54+
55+
##### Responses
56+
57+
> | http code | content-type | response |
58+
> | --------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |
59+
> | `200` | `application/json` | `{"access_token": <access_token>, "token_type": "Bearer", "expiration_timestamp": <expiration_timestamp>}` |
60+
> | `404` | `application/json` | `{"error":"Invalid User"}` |
61+
62+
##### Example cURL
63+
64+
> ```javascript
65+
> curl -X POST -H "Content-Type: application/json" -d '{"user_id": <user_id>}' <url>/api/token
66+
> ```
67+
68+
</details>
69+
70+
---
71+
72+
#### Subscribing
73+
74+
<details>
75+
<summary><code>POST</code> <code><b>/api/subscribe</b></code> <code>(Subscribes to one course)</code></summary>
76+
77+
##### Parameters
78+
79+
> | name | type | data type | description |
80+
> | ---- | -------- | ----------- | --------------------------------------------------------------------------------------- |
81+
> | None | required | object JSON | `{"course": <course_name>, "class": <class_identifier>, "webhook_url": <webhook_url>"}` |
82+
83+
##### Responses
84+
85+
> | http code | content-type | response |
86+
> | --------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
87+
> | `200` | `application/json` | `{"user":{"id":<user_id>}, "course": <course_identifier>, "class": <class_identifier> "webhook_url": <webhook_url>` |
88+
> | `400` | `application/json` | `{"error":"Invalid token"}` |
89+
> | `400` | `application/json` | `{"error":"Missing credentials"}` |
90+
> | `422` | `text/plain; charset=utf-8` | `<Error Message about missing attributes>}` |
91+
92+
##### Example cURL
93+
94+
> ```javascript
95+
> curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <bearer_token>" -d '{"course": <course_name>, "class": <class_identifier", "webhook_url": "<webhook_url>"}' <url>/subscribe
96+
> ```
97+
98+
</details>
99+
100+
<details>
101+
<summary><code>POST</code> <code><b>/api/subscribe/all</b></code> <code>(Subscribes to every course)</code></summary>
102+
103+
##### Parameters
104+
105+
> | name | type | data type | description |
106+
> | ---- | -------- | ----------- | -------------------------------- |
107+
> | None | required | object JSON | `{"webhook_url": <webhook_url>}` |
108+
109+
##### Responses
110+
111+
> | http code | content-type | response |
112+
> | --------- | --------------------------- | -------------------------------------------------------- |
113+
> | `200` | `application/json` | `{"user":{"id":<user_id>}, "webhook_url": <webhook_url>` |
114+
> | `400` | `application/json` | `{"error":"Invalid token"}` |
115+
> | `400` | `application/json` | `{"error":"Missing credentials"}` |
116+
> | `422` | `text/plain; charset=utf-8` | `<Error Message about missing attributes>}` |
117+
118+
##### Example cURL
119+
120+
> ```javascript
121+
> curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <bearer_token>" -d '{"webhook_url": "<webhook_url>"}' <url>/subscribe/all
122+
> ```
123+
124+
</details>
125+
126+
---
127+
128+
#### Submiting a grade
129+
130+
</details>
131+
132+
<details>
133+
<summary><code>POST</code> <code><b>/api/grade</b></code> <code>(Submits a grade)</code></summary>
134+
135+
##### Parameters
136+
137+
> | name | type | data type | description |
138+
> | ---- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
139+
> | None | required | object JSON | `{"name": <grade_identifier>, "course": <course_name>, "class": <class_identifier>, "class_average": <grade_class_average>}` |
140+
141+
##### Responses
142+
143+
> | http code | content-type | response |
144+
> | --------- | --------------------------- | ------------------------------------------- |
145+
> | `201` | `text/plain; charset=utf-8` | `Grade Created` |
146+
> | `409` | `text/plain; charset=utf-8` | `Grade already exists` |
147+
> | `400` | `application/json` | `{"error":"Invalid token"}` |
148+
> | `400` | `application/json` | `{"error":"Missing credentials"}` |
149+
> | `422` | `text/plain; charset=utf-8` | `<Error Message about missing attributes>}` |
150+
151+
##### Example cURL
152+
153+
> ```javascript
154+
> curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <bearer_token>" -d '{"course":<course_name>, "class":<class_identifier>, "name":<grade_identifier>, "class_average": <grade_class_average>}' <url>/api/grade
155+
> ```
156+
157+
</details>
158+
159+
---
160+
161+
### Admin Space
162+
163+
---
164+
165+
#### Create a user
166+
167+
<details>
168+
<summary><code>POST</code> <code><b>/api/user</b></code> <code>(Creates a new user)</code></summary>
169+
170+
##### Parameters
171+
172+
- No parameters
173+
174+
##### Responses
175+
176+
> | http code | content-type | response |
177+
> | --------- | ------------------ | --------------------------------- |
178+
> | `200` | `application/json` | `{"id": <user_id>}` |
179+
> | `400` | `application/json` | `{"error":"Invalid token"}` |
180+
> | `400` | `application/json` | `{"error":"Missing credentials"}` |
181+
> | `401` | `` | `<Unauthorized>` |
182+
183+
##### Example cURL
184+
185+
> ```javascript
186+
> curl -X POST -H "Authorization: Bearer <admin_token>" <url>/api/user
187+
> ```
188+
189+
</details>
190+
191+
---
192+
193+
## Code
194+
195+
- The source code is written in [rust](https://www.rust-lang.org/) using the (axum)[https://docs.rs/axum/latest/axum/] framework
196+
197+
## Deploying
198+
199+
### Docker
200+
201+
- A docker image is available [here](https://github.com/AndreCostaaa/gaps-notifier-api/pkgs/container/gaps-notifier-api)
202+
203+
### Requirements
204+
205+
- [redis](https://redis.io/)
206+
- Environnement variables:
207+
208+
```env
209+
JWT_SECRET
210+
ADMIN_TOKEN
211+
REDIS_URL
212+
```
213+
214+
Admin token is the static bearer token for admin usage
215+
216+
## License
217+
218+
This application is licensed under the GNU General Public License v3.0. It is open to everyone to use and modify as they wish, in accordance with the license's terms and conditions.

0 commit comments

Comments
 (0)