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

refactored backend docs

Browse Source
This commit is contained in:
Theis Gaedigk
2025-11-17 22:52:58 +01:00
parent 084a0fa2e2
commit a191c9c053
1 changed files with 152 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

263
Docs/backend_API_docs/README.md
View File

@@ -1,74 +1,63 @@
# Backend API docs
# Backend API (V2) Documentation
If you want to cooperate with me, or build something new with my backend API, feel free to reach out!
This document describes the current backend API routes and their real response shapes.
On this page you will learn how my API works.
## Base URLs
## General information
- Frontend: https://insta.the1s.de
- Backend: https://backend.insta.the1s.de
- Base path: https://backend.insta.the1s.de/api
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 `api.route.js` and `api.database.js`.
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.
---
## Base URL
- Frontend: `https://insta.the1s.de`
- Backend: `https://backend.insta.the1s.de`
- Base path for this API: `https://backend.insta.the1s.de/api`
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)_
Service status: https://status.the1s.de
---
## Authentication
All endpoints require an API key as a path parameter named `:key`.
All protected endpoints (except `/api/all-items`) require an API key as a path parameter `:key`.
**The API key must be always 15 characters long and can only contain numbers.**
Rules:
You can get the API key from the admin dashboard.
- Exactly 15 characters
- Digits only
Example: `/api/items/:key`
Example:
If the key is missing or invalid, the API responds with `401 Unauthorized`.
```
GET /api/items/123456789012345
```
### Files
Error if missing/invalid: `401 Unauthorized`.
**You can find the authentication files here:**
Auth modules:
- `backendV2/services/authentication.js`
- `backendV2/services/database.js`
- backendV2/services/authentication.js
- backendV2/services/database.js
**The API routes are located here:**
Route handlers:
- `backendV2/routes/api/api.route.js`
- `backendV2/services/api/api.database.js`
- backendV2/routes/api/api.route.js
- backendV2/routes/api/api.database.js
---
## Endpoints
### 1) Get all items
### 1) Get all items (authenticated)
GET `/api/items/:key`
Returns a list of all items wrapped in a `data` object.
Returns all items wrapped in a `data` object.
Example request:
Example:
```
GET https://backend.insta.the1s.de/api/items/12345
GET https://backend.insta.the1s.de/api/items/123456789012345
```
Example response:
Successful response (example structure; actual columns depend on table):
```
```json
{
"data": [
{
@@ -76,151 +65,203 @@ Example response:
"item_name": "DJI 1er Mikro",
"can_borrow_role": 4,
"inSafe": 1,
"currently_borrowing": null,
"last_borrowed_person": "alice",
"entry_created_at": "2025-08-19T22:02:16.000Z"
}
]
}
```
Fields:
Status codes:
- `id`: Unique identifier
- `item_name`: Item name
- `can_borrow_role`: Role allowed to borrow
- `inSafe`: 1 if in locker, 0 otherwise
- `entry_created_at`: Creation timestamp
- 200 success
- 500 database error
Status: 200 on success, 500 on failure.
---
### 2) Change item safe state
### 2) Toggle item safe state (authenticated)
POST `/api/change-state/:key/:itemId/:state`
Updates `inSafe` (locker) state of an item.
Parameters:
- `state` must be `"1"` (in safe) or `"0"` (not in safe)
- `itemId`: numeric item ID
- `state`: must be `"1"` or `"0"` (validated), but the current implementation IGNORES this value and toggles `inSafe` (SQL uses `SET inSafe = NOT inSafe`).
Example request:
Example:
```
POST https://backend.insta.the1s.de/api/controlInSafe/12345/123/1
POST https://backend.insta.the1s.de/api/change-state/123456789012345/42/1
```
Example response (shape depends on database service):
Current success response:
```
{ "data": { /* update result */ } }
```json
{}
```
Status:
(Empty object because the handler sends `{ data: result.data }` and the database layer returns no `data`.)
- 200 on success
- 400 if `state` is invalid
- 500 on failure
Status codes:
**You can get the item id on the admin panel, from your system administrator.**
- 200 toggled
- 400 invalid `state` (anything other than "0"/"1")
- 500 failure
---
Note: To actually set a specific state, the database function would need adjustment.
### 3) Get loan by code
### 3) Get loan by code (authenticated)
GET `/api/get-loan-by-code/:key/:loan_code`
Retrieves the details of a specific loan.
Returns limited loan fields (current implementation selects only: `username, returned_date, take_date, lockers`).
Example request:
Example:
```
GET https://backend.insta.the1s.de/api/getLoanByCode/12345/123456
GET https://backend.insta.the1s.de/api/get-loan-by-code/123456789012345/646473
```
Example response:
Response (if found):
```
```json
{
"data": {
"id": 6,
"username": "theis",
"loan_code": 646473,
"start_date": "2025-08-25T13:23:00.000Z",
"end_date": "2025-08-26T13:23:00.000Z",
"take_date": null,
"returned_date": null,
"created_at": "2025-08-20T11:23:40.000Z",
"loaned_items_id": [8, 9],
"loaned_items_name": ["SD Karten", "Kameragimbal"]
"take_date": "2025-08-25T13:23:00.000Z",
"lockers": "A2"
}
}
```
Status:
Status codes:
- 200 on success
- 404 if not found
- 200 found
- 404 not found
---
### 4) Set return date (now) by loan code
### 4) Set return date (authenticated)
POST `/api/set-return-date/:key/:loan_code`
Sets the `returned_date` to the current server time.
Sets `returned_date = NOW()` for the loan. Also updates all linked items:
**Note:** I have updated this API route, so that everytime you return or take a loan, the state of the loaned items is automatically updated.
- `inSafe = 1`
- `currently_borrowing = NULL`
- `last_borrowed_person = <loan owner username>`
**DO NOT UPDATE THE STATE MANUALLY! (only if the item was taken with an admin key)**
Example request:
Example:
```
POST https://backend.insta.the1s.de/api/setReturnDate/12345/123456
POST https://backend.insta.the1s.de/api/set-return-date/123456789012345/646473
```
Example response:
Response on success:
```
{ "data": { /* update result */ } }
```json
{}
```
Status: 200 on success, 500 on failure.
Status codes:
---
- 200 success
- 500 failure
### 5) Set take date (now) by loan code
### 5) Set take date (authenticated)
POST `/api/set-take-date/:key/:loan_code`
Sets the `take_date` to the current server time.
Sets `take_date = NOW()` for the loan. Also updates linked items:
**Note:** I have updated this API route, so that everytime you return or take a loan, the state of the loaned items is automatically updated.
- `inSafe = 0`
- `currently_borrowing = <loan owner username>`
**DO NOT UPDATE THE STATE MANUALLY! (only if the item was taken with an admin key)**
Example request:
Example:
```
POST https://backend.insta.the1s.de/api/setTakeDate/12345/123456
POST https://backend.insta.the1s.de/api/set-take-date/123456789012345/646473
```
Example response:
Response on success:
```
{ "data": { /* update result */ } }
```json
{}
```
Status: 200 on success, 500 on failure.
Status codes:
- 200 success
- 500 failure
### 6) Get all items (public, no key)
GET `/api/all-items`
Same data as endpoint (1) but NOT wrapped in `data`.
Example:
```
GET https://backend.insta.the1s.de/api/all-items
```
Response:
```json
[
{
"id": 1,
"item_name": "DJI 1er Mikro",
"can_borrow_role": 4,
"inSafe": 1,
"currently_borrowing": null,
"last_borrowed_person": "alice",
"entry_created_at": "2025-08-19T22:02:16.000Z"
}
]
```
Status codes:
- 200 success
- 500 failure
---
## Error handling
## Response Summary
- 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
Common success forms:
- List (wrapped): `{ "data": [ ... ] }`
- Single loan: `{ "data": { ... } }`
- Mutation (current implementation): `{}` (no payload)
Errors:
```json
{ "message": "Failed to fetch items" }
{ "message": "Failed to update item state" }
{ "message": "Invalid state value" }
{ "message": "Loan not found" }
{ "message": "Failed to set return date" }
{ "message": "Failed to set take date" }
```
Status Codes:
- 200 OK
- 400 Bad Request (invalid state param)
- 401 Unauthorized (invalid/missing key)
- 404 Not Found (loan)
- 500 Internal Server Error (database/update failure)
---
If you have questions or want to collaborate, please reach out!
## Notes / Implementation Gaps
- `change-state` ignores requested `state` and toggles instead.
- Mutation endpoints return empty JSON; include a result object if feedback is needed.
- `get-loan-by-code` returns fewer fields than earlier documentation suggested.
---
For collaboration, reach out via the admin channel.