Matthias-Claudius-Schule/borrow-system
3
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

changed docs

Browse Source
This commit is contained in:
Theis Gaedigk
2025-09-27 23:29:08 +02:00
parent fc755edadf
commit a4c0323100
1 changed files with 108 additions and 212 deletions
Download Patch File Download Diff File Expand all files Collapse all files

320
Docs/backend_API_docs/README.md
View File

@@ -1,4 +1,4 @@
# Backend API docs # Backend API docs (apiV2)
If you want to cooperate with me, or build something new with my backend API, feel free to reach out! If you want to cooperate with me, or build something new with my backend API, feel free to reach out!
@@ -6,49 +6,51 @@ On this page you will learn how my API works.
## General information ## General information
When you look at my backend folder and file structure, you can see that I have two files called `API`. The first file called `api.js` is for my web frontend, because this file works together with my JWT token service. When you look at my backend folder and file structure, you can see that I have two files called `API`. The first file called `api.js` which is for my web frontend, because this file works together with my JWT token service.
**\*But I have built a second API. You can see the second API file in the same directory, the file is called `apiV2.js`.** But I have built a second API. You can see the second API file in the same directory, the file is called `apiV2.js`.
This is the file that you can use to build an API. But first you have to get an API Key. You can get the API key from my admin dashboard. When you don't have any access to my admin dashboard, please contact your administrator or me.
But first you have to get the Admin API key, stored in an `.env` file on my server. ---
## Base URL
- Frontend: `https://insta.the1s.de`
- Backend: `https://backend.insta.the1s.de`
- Base path for this API: `https://backend.insta.the1s.de/apiV2`
You can see the status of this and all my other services at `https://status.the1s.de`.
_I have also build a [fallback page](https://git.the1s.de/theis.gaedigk/fallback-page). When only the application is down, you will see a friendly message and a link to the status page. (Only if the server is not down)_
--- ---
## Authentication ## Authentication
All endpoints require the Admin API key (`ADMIN_ID`) as a URL parameter. All endpoints require an API key as a path parameter named `:key`.
Example: `/apiV2/items/{ADMIN_ID}` Example: `/apiV2/items/:key`
If the key is missing or invalid, the API responds with `401 Unauthorized`.
--- ---
## URL ## Endpoints
- The frontend is currently running on `https://insta.the1s.de`. ### 1) Get all items
- The backend is currently running on `https://backend.insta.the1s.de`. GET `/apiV2/items/:key`
You can see the status of this and all my other services at `https://status.the1s.de`. Returns a list of all items wrapped in a `data` object.
--- Example request:
## Current endpoints
### 1. Get All Items
**GET** `/apiV2/items/:key`
Returns a list of all items and their details.
#### Example Request
``` ```
GET https://backend.insta.the1s.de/apiV2/items/your_admin_key GET https://backend.insta.the1s.de/apiV2/items/12345
``` ```
#### Example Response Example response:
``` ```
{ {
@@ -59,206 +61,66 @@ GET https://backend.insta.the1s.de/apiV2/items/your_admin_key
"can_borrow_role": 4, "can_borrow_role": 4,
"inSafe": 1, "inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z" "entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 2,
"item_name": "DJI 2er Mikro 1",
"can_borrow_role": 4,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 3,
"item_name": "DJI 2er Mikro 2",
"can_borrow_role": 4,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 4,
"item_name": "Rode Richt Mikrofon",
"can_borrow_role": 2,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 5,
"item_name": "Kamera Stativ",
"can_borrow_role": 1,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 6,
"item_name": "SONY Kamera - inkl. Akkus und Objektiv",
"can_borrow_role": 1,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 7,
"item_name": "MacBook inkl. Adapter",
"can_borrow_role": 2,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 8,
"item_name": "SD Karten",
"can_borrow_role": 3,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 9,
"item_name": "Kameragimbal",
"can_borrow_role": 1,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 10,
"item_name": "ATEM MINI PRO",
"can_borrow_role": 1,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 11,
"item_name": "Handygimbal",
"can_borrow_role": 4,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 12,
"item_name": "Kameralfter",
"can_borrow_role": 1,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 13,
"item_name": "Kleine Kamera 1 - inkl. Objektiv",
"can_borrow_role": 2,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
},
{
"id": 14,
"item_name": "Kleine Kamera 2 - inkl. Objektiv",
"can_borrow_role": 2,
"inSafe": 1,
"entry_created_at": "2025-08-19T22:02:16.000Z"
} }
] ]
} }
``` ```
Each item has the following properties: Fields:
- `id`: The unique identifier for the item. - `id`: Unique identifier
- `item_name`: The name of the item. - `item_name`: Item name
- `can_borrow_role`: The role ID that is allowed to borrow the item. - `can_borrow_role`: Role allowed to borrow
- `inSafe`: Indicates whether the item is currently in the locker (1) or not (0). This variable/state can change over time. - `inSafe`: 1 if in locker, 0 otherwise
- `entry_created_at`: Creation timestamp
_You also get an http 200 status code._ Status: 200 on success, 500 on failure.
--- ---
### 2. Change Item Safe State ### 2) Change item safe state
**POST** `/apiV2/controlInSafe/:key/:itemId/:state` POST `/apiV2/controlInSafe/:key/:itemId/:state`
Updates the `inSafe` state of an item (whether it is in the locker). Updates `inSafe` (locker) state of an item.
- `state` must be `"1"` (in safe) or `"0"` (not in safe). - `state` must be `"1"` (in safe) or `"0"` (not in safe)
#### Example Request Example request:
``` ```
POST https://backend.insta.the1s.de/apiV2/controlInSafe/your_admin_key/item_id/new_item_state POST https://backend.insta.the1s.de/apiV2/controlInSafe/12345/123/1
``` ```
#### Example Response Example response (shape depends on database service):
``` ```
{} { "data": { /* update result */ } }
``` ```
_An empty object means, that the operation was successful and no further information is returned._ Status:
_You also get an http 200 status code._ - 200 on success
- 400 if `state` is invalid
- 500 on failure
**You can get the item id on the admin panel, from your system administrator.**
--- ---
### 3. Set Return Date ### 3) Get loan by code
**POST** `/apiV2/setReturnDate/:key/:loan_code` GET `/apiV2/getLoanByCode/:key/:loan_code`
Sets the `returned_date` of a loan to the current server time. Retrieves the details of a specific loan.
- `loan_code`: The unique code of the loan. Example request:
#### Example Request
``` ```
POST https://backend.insta.the1s.de/apiV2/setReturnDate/your_admin_key/your_loan_code GET https://backend.insta.the1s.de/apiV2/getLoanByCode/12345/123456
``` ```
#### Example Response Example response:
```
{}
```
_An empty object means, that the operation was successful and no further information is returned._
_You also get an http 200 status code._
---
### 4. Set Take Date
**POST** `/apiV2/setTakeDate/:key/:loan_code`
Sets the `take_date` of a loan to the current server time.
- `loan_code`: The unique code of the loan.
#### Example Request
```
POST https://backend.insta.the1s.de/apiV2/setTakeDate/your_admin_key/your_loan_code
```
#### Example Response
```
{}
```
_An empty object means, that the operation was successful and no further information is returned._
_You also get an http 2xx status code._
---
### 5. Get whole loan by loan code
**POST** `/getLoanByCode/:key/:loan_code`
Retrieves the details of a specific loan by its unique code.
- `loan_code`: The unique code of the loan.
#### Example Request
```
GET https://backend.insta.the1s.de/getLoanByCode/your_admin_key/your_loan_code
```
#### Example Response
``` ```
{ {
@@ -271,36 +133,70 @@ GET https://backend.insta.the1s.de/getLoanByCode/your_admin_key/your_loan_code
"take_date": null, "take_date": null,
"returned_date": null, "returned_date": null,
"created_at": "2025-08-20T11:23:40.000Z", "created_at": "2025-08-20T11:23:40.000Z",
"loaned_items_id": [ "loaned_items_id": [8, 9],
8, "loaned_items_name": ["SD Karten", "Kameragimbal"]
9
],
"loaned_items_name": [
"SD Karten",
"Kameragimbal"
]
} }
} }
``` ```
_You also get an http 200 status code._ Status:
If the loan id does not exist, you will receive a 404 status code and an error message. - 200 on success
- 404 if not found
```
{
"message": "Loan not found"
}
```
--- ---
## Error Handling ### 4) Set return date (now) by loan code
- `403 Forbidden`: Invalid or missing API key. POST `/apiV2/setReturnDate/:key/:loan_code`
- `400 Bad Request`: Invalid parameters (e.g., wrong state value).
- `500 Internal Server Error`: Database or server error. Sets the `returned_date` to the current server time.
Example request:
```
POST https://backend.insta.the1s.de/apiV2/setReturnDate/12345/123456
```
Example response:
```
{ "data": { /* update result */ } }
```
Status: 200 on success, 500 on failure.
--- ---
If you have questions or want to collaborate, please reach out to me! ### 5) Set take date (now) by loan code
POST `/apiV2/setTakeDate/:key/:loan_code`
Sets the `take_date` to the current server time.
Example request:
```
POST https://backend.insta.the1s.de/apiV2/setTakeDate/12345/123456
```
Example response:
```
{ "data": { /* update result */ } }
```
Status: 200 on success, 500 on failure.
---
## Error handling
- 401 Unauthorized: Missing or invalid API key
- 400 Bad Request: Invalid parameters (e.g., wrong state value)
- 404 Not Found: Loan not found
- 500 Internal Server Error: Database or server error
---
If you have questions or want to collaborate, please reach out!