From fc755edadf6c251b0eef27fb2236cd94908f7adf Mon Sep 17 00:00:00 2001 From: Theis Gaedigk Date: Sat, 27 Sep 2025 23:06:21 +0200 Subject: [PATCH 1/3] fixed scheme --- backend/scheme.sql | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/backend/scheme.sql b/backend/scheme.sql index 505c1b6..e7d9c81 100644 --- a/backend/scheme.sql +++ b/backend/scheme.sql @@ -63,8 +63,7 @@ CREATE TABLE `apiKeys` ( `apiKey` int NOT NULL UNIQUE, `user` VARCHAR(255) NOT NULL, `entry_created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP, - PRIMARY KEY (`id`), - UNIQUE KEY `apiKey` (`apiKey`) + PRIMARY KEY (`id`) ); INSERT INTO `items` (`item_name`, `can_borrow_role`, `inSafe`) VALUES From a4c0323100ac5d4f386c7a61317f58bf3372c9c6 Mon Sep 17 00:00:00 2001 From: Theis Gaedigk Date: Sat, 27 Sep 2025 23:29:08 +0200 Subject: [PATCH 2/3] changed docs --- Docs/backend_API_docs/README.md | 320 +++++++++++--------------------- 1 file changed, 108 insertions(+), 212 deletions(-) diff --git a/Docs/backend_API_docs/README.md b/Docs/backend_API_docs/README.md index 2f005ae..ee866cf 100644 --- a/Docs/backend_API_docs/README.md +++ b/Docs/backend_API_docs/README.md @@ -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! @@ -6,49 +6,51 @@ On this page you will learn how my API works. ## 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 -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. ---- - -## Current endpoints - -### 1. Get All Items - -**GET** `/apiV2/items/:key` - -Returns a list of all items and their details. - -#### Example Request +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, "inSafe": 1, "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. -- `item_name`: The name of the item. -- `can_borrow_role`: The role ID that is allowed to borrow the item. -- `inSafe`: Indicates whether the item is currently in the locker (1) or not (0). This variable/state can change over time. +- `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 -_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 - -``` -{} -``` - -_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 +Example response: ``` { @@ -271,36 +133,70 @@ GET https://backend.insta.the1s.de/getLoanByCode/your_admin_key/your_loan_code "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" - ] + "loaned_items_id": [8, 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. - -``` -{ - "message": "Loan not found" -} -``` +- 200 on success +- 404 if not found --- -## Error Handling +### 4) Set return date (now) by loan code -- `403 Forbidden`: Invalid or missing API key. -- `400 Bad Request`: Invalid parameters (e.g., wrong state value). -- `500 Internal Server Error`: Database or server error. +POST `/apiV2/setReturnDate/:key/:loan_code` + +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! From eff1f6142207aa9136fe65ac7981ddd19b717311 Mon Sep 17 00:00:00 2001 From: Theis Gaedigk Date: Sat, 27 Sep 2025 23:29:19 +0200 Subject: [PATCH 3/3] Refactor API routes: remove API key requirement for allLoans and allItems endpoints, update comments for clarity --- backend/routes/apiV2.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/backend/routes/apiV2.js b/backend/routes/apiV2.js index 15f994d..1d32c54 100644 --- a/backend/routes/apiV2.js +++ b/backend/routes/apiV2.js @@ -111,8 +111,8 @@ router.post("/setTakeDate/:key/:loan_code", apiKeyGuard, async (req, res) => { } }); -// Route for API to get ALL loans from the database without sensitive info -router.get("/allLoans/:key", apiKeyGuard, async (req, res) => { +// Route for API to get ALL loans from the database without sensitive info (only for landingpage) +router.get("/allLoans", async (req, res) => { const result = await getAllLoansV2(); if (result.success) { return res.status(200).json(result.data); @@ -120,8 +120,8 @@ router.get("/allLoans/:key", apiKeyGuard, async (req, res) => { return res.status(500).json({ message: "Failed to fetch loans" }); }); -// Route for API to get ALL items form the database -router.get("/allItems/:key", apiKeyGuard, async (req, res) => { +// Route for API to get ALL items from the database (only for landingpage) +router.get("/allItems", async (req, res) => { const result = await getItemsFromDatabaseV2(); if (result.success) { res.status(200).json(result.data);