borrow-system/Docs/backend_API_docs/README.md

Backend API (V2) Documentation

This document describes the current backend API routes and their real response shapes.

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

All protected endpoints (except /api/all-items) require an API key as a path parameter :key.

Rules:

• Exactly 15 characters
• Digits only

Example:

GET /api/items/123456789012345

Error if missing/invalid: 401 Unauthorized.

Auth modules:

• backendV2/services/authentication.js
• backendV2/services/database.js

Route handlers:

• backendV2/routes/api/api.route.js
• backendV2/routes/api/api.database.js

---

Endpoints

1) Get all items (authenticated)

GET /api/items/:key

Returns all items wrapped in a data object.

Example:

GET https://backend.insta.the1s.de/api/items/123456789012345

Successful response (example structure; actual columns depend on table):

{
  "data": [
    {
      "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 database error

2) Toggle item safe state (authenticated)

POST /api/change-state/:key/:itemId/:state

Parameters:

• 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:

POST https://backend.insta.the1s.de/api/change-state/123456789012345/42/1

Current success response:

{}

(Empty object because the handler sends { data: result.data } and the database layer returns no data.)

Status codes:

• 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 (authenticated)

GET /api/get-loan-by-code/:key/:loan_code

Returns limited loan fields (current implementation selects only: username, returned_date, take_date, lockers).

Example:

GET https://backend.insta.the1s.de/api/get-loan-by-code/123456789012345/646473

Response (if found):

{
  "data": {
    "username": "theis",
    "returned_date": null,
    "take_date": "2025-08-25T13:23:00.000Z",
    "lockers": "A2"
  }
}

Status codes:

• 200 found
• 404 not found

4) Set return date (authenticated)

POST /api/set-return-date/:key/:loan_code

Sets returned_date = NOW() for the loan. Also updates all linked items:

• inSafe = 1
• currently_borrowing = NULL
• last_borrowed_person = <loan owner username>

Example:

POST https://backend.insta.the1s.de/api/set-return-date/123456789012345/646473

Response on success:

{}

Status codes:

• 200 success
• 500 failure

5) Set take date (authenticated)

POST /api/set-take-date/:key/:loan_code

Sets take_date = NOW() for the loan. Also updates linked items:

• inSafe = 0
• currently_borrowing = <loan owner username>

Example:

POST https://backend.insta.the1s.de/api/set-take-date/123456789012345/646473

Response on success:

{}

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:

[
  {
    "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

---

Response Summary

Common success forms:

• List (wrapped): { "data": [ ... ] }
• Single loan: { "data": { ... } }
• Mutation (current implementation): {} (no payload)

Errors:

{ "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)

---

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.