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

edited docs

Browse Source
This commit is contained in:
Theis Gaedigk
2025-11-25 17:09:22 +01:00
parent 4c60fea4c4
commit 3bf5560834
1 changed files with 221 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

414
Docs/backend_API_docs/README.md
View File

@@ -1,87 +1,88 @@
# Backend API (V2) Documentation # Borrow System API Documentation
This document describes the current backend API routes and their real response shapes, based on the code in `backendV2`. **Frontend:** https://insta.the1s.de
**Backend base URL:** `https://backend.insta.the1s.de/api`
---
## Base URLs
- Frontend: `https://insta.the1s.de`
- Backend: `https://backend.insta.the1s.de`
- Base path: `https://backend.insta.the1s.de/api`
Service status: `https://status.the1s.de`
--- ---
## Authentication ## Authentication
All **protected** endpoints require an API key as a path parameter `:key`. All API endpoints require **either**:
Rules for `:key`: ### 1. Bearer Token (JWT)
- Exactly 8 characters Send an `Authorization` header:
- Digits only (`^[0-9]{8}$`)
```http
Authorization: Bearer <JWT_TOKEN>
```
- Used for user-based access.
- Token must be valid and not expired.
### 2. API Key (for devices / machine-to-machine)
Include an API key in the route as `:key` parameter:
```text
/api/.../:key/...
```
Example: Example:
```http ```http
GET /api/items/12345678 GET /api/items/ABC123
``` ```
On missing / invalid key: Where `ABC123` is your API key.
The API key is validated server-side.
- Status: `401 Unauthorized`
- Body (exact message depends on `authenticate` in `backendV2/services/authentication.js`)
Auth-related modules:
- `backendV2/services/authentication.js`
- `backendV2/services/database.js`
Route handlers:
- `backendV2/routes/api/api.route.js`
- `backendV2/routes/api/api.database.js`
--- ---
## Endpoints (Overview) ## Common Response Codes
1. **Public** - `200 OK` – Request was successful.
- `401 Unauthorized` – Missing or malformed credentials.
- `GET /api/all-items` – List all items (no auth; from original docs) - `403 Forbidden` – Credentials invalid or not allowed to access this resource.
- `404 Not Found` – Resource (e.g., loan) not found.
2. **Items (authenticated)** - `500 Internal Server Error` – Unexpected server error.
- `GET /api/items/:key` – List all items
- `POST /api/change-state/:key/:itemId/:state` – Toggle item safe state
3. **Loans (authenticated)**
- `GET /api/get-loan-by-code/:key/:loan_code` – Get loan by code
- `POST /api/set-take-date/:key/:loan_code` – Set “take” date and mark items as out
- `POST /api/set-return-date/:key/:loan_code` – Set “return” date and mark items as returned
--- ---
## 1) Items ## Endpoints
### 1.1 Get all items ### 1. Get All Items
**GET** `/api/items/:key` **GET** `/api/items/:key`
Returns all items wrapped in a `data` property. Returns a list of all items.
- Handler: `getItemsFromDatabaseV2` in `api.database.js` #### Path Parameters
- SQL: `SELECT * FROM items;`
#### Example request - `:key` – API key (string)
#### Authentication
- Either:
- Valid `Authorization: Bearer <token>`
- Or valid `:key` path parameter
#### Request Example
```http ```http
GET https://backend.insta.the1s.de/api/items/12345678 GET /api/items/ABC123 HTTP/1.1
Host: backend.insta.the1s.de
``` ```
#### Successful response or
```http
GET /api/items/dummyKey HTTP/1.1
Host: backend.insta.the1s.de
Authorization: Bearer <JWT_TOKEN>
```
#### Successful Response (200)
```json ```json
{ {
@@ -90,8 +91,9 @@ GET https://backend.insta.the1s.de/api/items/12345678
"id": 1, "id": 1,
"item_name": "DJI 1er Mikro", "item_name": "DJI 1er Mikro",
"can_borrow_role": 4, "can_borrow_role": 4,
"in_safe": 1, "inSafe": 1,
"safe_nr": "01", "safe_nr": 3,
"door_key": "123",
"entry_created_at": "2025-08-19T22:02:16.000Z", "entry_created_at": "2025-08-19T22:02:16.000Z",
"entry_updated_at": "2025-08-19T22:02:16.000Z", "entry_updated_at": "2025-08-19T22:02:16.000Z",
"last_borrowed_person": "alice", "last_borrowed_person": "alice",
@@ -101,245 +103,271 @@ GET https://backend.insta.the1s.de/api/items/12345678
} }
``` ```
#### Error response #### Error Response (500)
```json ```json
{ "message": "Failed to fetch items" } {
"message": "Failed to fetch items"
}
``` ```
#### Status codes
- `200 OK` – success, `data` is an array (possibly empty)
- `401 Unauthorized` – invalid / missing key
- `500 Internal Server Error` – database error or `success: false` from DB layer
--- ---
### 2.2 Toggle item safe state ### 2. Toggle Item Safe State
Toggles `in_safe` between `0` and `1` for a given item.
**Keep in mind that when you return a loan by code, the item states are automatically updated.**
**POST** `/api/change-state/:key/:itemId` **POST** `/api/change-state/:key/:itemId`
> You do not need this endpoint to set the states of the items when the items are taken out or returned. When you take or return a loan, the item states are set automatically by the loan endpoints. This endpoint is only for manually toggling the `inSafe` state of an item. #### Path Parameters
Path parameters: - `:key` – API key (string)
- `:itemId` – Item ID (integer)
- `:key` – API key (8 digits) #### Authentication
- `:itemId` – numeric `id` of the item
Handler in `api.route.js` calls `changeInSafeStateV2(itemId)`, which executes: - Either Bearer token or `:key` API key.
```sql #### Request Example
UPDATE items SET in_safe = NOT in_safe WHERE id = ?
```
#### Example request
```http ```http
POST https://backend.insta.the1s.de/api/change-state/12345678/42 POST /api/change-state/ABC123/42 HTTP/1.1
Host: backend.insta.the1s.de
``` ```
(Will toggle `in_safe` for item `42`.) #### Successful Response (200)
#### Successful response (current implementation)
```json ```json
{ {
"data": null "data": {}
} }
``` ```
#### Error responses _(Implementation currently only returns `{ success: true }`, so `data` may be empty.)_
Invalid `state` (anything other than `"0"` or `"1"`): #### Error Response (500)
```json ```json
{ "message": "Invalid state value" } {
"message": "Failed to update item state"
}
``` ```
Failed update:
```json
{ "message": "Failed to update item state" }
```
#### Status codes
- `200 OK` – item state toggled
- `400 Bad Request` – invalid `state` parameter
- `401 Unauthorized` – invalid / missing key
- `500 Internal Server Error` – database/update failure or `success: false` from DB layer
--- ---
## 3) Loans ### 3. Get Loan by Code
### 3.1 Get loan by code Fetch loan information by `loan_code`.
**GET** `/api/get-loan-by-code/:key/:loan_code` **GET** `/api/get-loan-by-code/:key/:loan_code`
Path parameters: #### Path Parameters
- `:key` – API key - `:key` – API key (string)
- `:loan_code` – 6-digit loan code (`^[0-9]{6}$` per DB constraint) - `:loan_code` – Loan code (string)
Database layer (`getLoanByCodeV2`) currently selects: #### Authentication
```sql - Either Bearer token or `:key` API key.
SELECT first_name, returned_date, take_date, lockers
FROM loans
WHERE loan_code = ?;
```
#### Example request #### Request Example
```http ```http
GET https://backend.insta.the1s.de/api/get-loan-by-code/12345678/646473 GET /api/get-loan-by-code/ABC123/12345 HTTP/1.1
Host: backend.insta.the1s.de
``` ```
#### Successful response #### Successful Response (200)
```json ```json
{ {
"data": { "data": {
"first_name": "Theis", "username": "john",
"returned_date": null, "returned_date": null,
"take_date": "2025-08-25T13:23:00.000Z", "take_date": "2025-01-01T10:00:00.000Z",
"lockers": ["01", "03"] "lockers": "[1, 2, 3]"
} }
} }
``` ```
#### Error response #### Error Response (404)
```json
{ "message": "Loan not found" }
```
#### Status codes
- `200 OK` – loan found
- `401 Unauthorized` – invalid / missing key
- `404 Not Found` – no matching loan for this `loan_code`
---
### 3.2 Set take date
**POST** `/api/set-take-date/:key/:loan_code`
Path parameters:
- `:key` – API key
- `:loan_code` – loan code
#### Example request
```http
POST https://backend.insta.the1s.de/api/set-take-date/12345678/646473
```
#### Successful response
```json ```json
{ {
"data": null "message": "Loan not found"
} }
``` ```
#### Error response
```json
{ "message": "Failed to set take date" }
```
#### Status codes
- `200 OK` – take date set and items marked as out
- `401 Unauthorized` – invalid / missing key
- `500 Internal Server Error` – invalid loan, missing items, or DB error / `success: false`
--- ---
### 3.3 Set return date ### 4. Set Loan Return Date
Sets `returned_date = NOW()` on a loan and updates related items:
- `in_safe = 1`
- `currently_borrowing = NULL`
- `last_borrowed_person = username`
**POST** `/api/set-return-date/:key/:loan_code` **POST** `/api/set-return-date/:key/:loan_code`
Path parameters: #### Path Parameters
- `:key` – API key - `:key` – API key (string)
- `:loan_code` – loan code - `:loan_code` – Loan code (string)
#### Example request #### Authentication
- Either Bearer token or `:key` API key.
#### Request Example
```http ```http
POST https://backend.insta.the1s.de/api/set-return-date/12345678/646473 POST /api/set-return-date/ABC123/12345 HTTP/1.1
Host: backend.insta.the1s.de
``` ```
#### Successful response (current implementation) #### Successful Response (200)
```json ```json
{ {
"data": null "data": {}
} }
``` ```
#### Error response #### Error Response (500)
```json ```json
{ "message": "Failed to set return date" } {
"message": "Failed to set return date"
}
``` ```
#### Status codes
- `200 OK` – return date set and items marked as returned
- `401 Unauthorized` – invalid / missing key
- `500 Internal Server Error` – invalid loan, missing items, or DB error / `success: false`
--- ---
## Common Response Shapes ### 5. Set Loan Take Date
**Success – list (authenticated items):** Sets `take_date = NOW()` on a loan and updates related items:
- `in_safe = 0`
- `currently_borrowing = username`
**POST** `/api/set-take-date/:key/:loan_code`
#### Path Parameters
- `:key` – API key (string)
- `:loan_code` – Loan code (string)
#### Authentication
- Either Bearer token or `:key` API key.
#### Request Example
```http
POST /api/set-take-date/ABC123/LOAN-12345 HTTP/1.1
Host: backend.insta.the1s.de
```
#### Successful Response (200)
```json ```json
{ {
"data": [ "data": {}
/* array of rows */
]
} }
``` ```
**Success – single loan:** #### Error Response (500)
```json
{
"message": "Failed to set take date"
}
```
---
### 6. Open Door by Door Key
Looks up an item by its `door_key`, toggles `in_safe`, and returns safe information.
**GET** `/api/open-door/:key/:doorKey`
#### Path Parameters
- `:key` – API key (string)
- `:doorKey` – Door key/token (string) used by hardware to identify the locker.
#### Authentication
- Either Bearer token or `:key` API key.
#### Request Example
```http
GET /api/open-door/ABC123/123 HTTP/1.1
Host: backend.insta.the1s.de
```
#### Successful Response (200)
```json ```json
{ {
"data": { "data": {
/* selected loan fields */ "safe_nr": 5,
"id": 42
} }
} }
``` ```
**Success – mutations (current code):** #### Error Response (500)
```json ```json
{ "data": null } {
"message": "Failed to open door"
}
``` ```
**Errors:** ---
## Authentication Error Messages
### Missing credentials
Status: `401`
```json ```json
{ "message": "Failed to fetch items" } {
{ "message": "Failed to update item state" } "message": "Unauthorized"
{ "message": "Invalid state value" } }
{ "message": "Loan not found" }
{ "message": "Failed to set return date" }
{ "message": "Failed to set take date" }
``` ```
**HTTP Status Codes:** ### Invalid JWT
- `200 OK` – operation succeeded Status: `403`
- `400 Bad Request` – invalid `state` parameter
- `401 Unauthorized` – invalid/missing API key ```json
- `404 Not Found` – loan not found {
- `500 Internal Server Error` – database / server failure or `success: false` from DB layer "message": "Present token invalid"
}
```
### Invalid API Key
Status: `403`
```json
{
"message": "API Key invalid"
}
```
---
## Notes
- All responses are JSON.
- Time fields like `take_date` and `returned_date` are in the format returned by MySQL (usually ISO-like strings).
- `loaned_items_id` in the database is stored as a JSON array string (e.g. `"[1,2,3]"`) and is parsed internally; clients do not interact with this field directly via current endpoints.