borrow-system/Docs/backend_API_docs/README.md

Borrow System API Documentation

Frontend: https://insta.the1s.de
Backend base URL: https://insta.the1s.de/backend/api

---

Authentication

All API endpoints require either:

1. Bearer Token (JWT)

Send an Authorization header:

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:

/api/.../:key/...

Example:

GET /api/items/12345678

Where 12345678 is your API key.
The API key is validated server-side.

---

Common Response Codes

• 200 OK – Request was successful.
• 401 Unauthorized – Missing or malformed credentials.
• 403 Forbidden – Credentials invalid or not allowed to access this resource.
• 404 Not Found – Resource (e.g., loan) not found.
• 500 Internal Server Error – Unexpected server error.

---

Endpoints

1. Get All Items

GET /api/items/:key

Returns a list of all items.

Path Parameters

• :key – API key (8-digit number)

Authentication

• Either:
  • Valid Authorization: Bearer <token>
  • Or valid :key path parameter

Request Example

GET /api/items/12345678 HTTP/1.1
Host: backend.insta.the1s.de
Authorization: Bearer <JWT_TOKEN>

Successful Response (200)

{
  "data": [
    {
      "id": 1,
      "item_name": "DJI 1er Mikro",
      "can_borrow_role": 4,
      "inSafe": 1,
      "safe_nr": 3,
      "door_key": "123",
      "entry_created_at": "2025-08-19T22:02:16.000Z",
      "entry_updated_at": "2025-08-19T22:02:16.000Z",
      "last_borrowed_person": "alice",
      "currently_borrowing": null
    }
  ]
}

Error Response (500)

{
  "message": "Failed to fetch items"
}

---

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

Path Parameters

• :key – API key (8-digit number)
• :itemId – Item ID (integer)

Authentication

• Either Bearer token or :key API key.

Request Example

POST /api/change-state/12345678/42 HTTP/1.1
Host: backend.insta.the1s.de

Successful Response (200)

{
  "data": {}
}

(Implementation currently only returns { success: true }, so data may be empty.)

Error Response (500)

{
  "message": "Failed to update item state"
}

---

3. Get Loan by Code

Fetch loan information by loan_code.

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

Path Parameters

• :key – API key (8-digit number)
• :loan_code – Loan code (string)

Authentication

• Either Bearer token or :key API key.

Request Example

GET /api/get-loan-by-code/12345678/12345 HTTP/1.1
Host: backend.insta.the1s.de

Successful Response (200)

{
  "data": {
    "username": "john",
    "returned_date": null,
    "take_date": "2025-01-01T10:00:00.000Z",
    "lockers": "[1, 2, 3]"
  }
}

Error Response (404)

{
  "message": "Loan not found"
}

---

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

Path Parameters

• :key – API key (8-digit number)
• :loan_code – Loan code (string)

Authentication

• Either Bearer token or :key API key.

Request Example

POST /api/set-return-date/12345678/12345 HTTP/1.1
Host: backend.insta.the1s.de

Successful Response (200)

{
  "data": {}
}

Error Response (500)

{
  "message": "Failed to set return date"
}

---

5. Set Loan Take Date

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 (8-digit number)
• :loan_code – Loan code (string)

Authentication

• Either Bearer token or :key API key.

Request Example

POST /api/set-take-date/12345678/LOAN-12345 HTTP/1.1
Host: backend.insta.the1s.de

Successful Response (200)

{
  "data": {}
}

Error Response (500)

{
  "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 (8-digit number)
• :doorKey – Door key/token (string) used by hardware to identify the locker.

Authentication

• Either Bearer token or :key API key.

Request Example

GET /api/open-door/12345678/123 HTTP/1.1
Host: backend.insta.the1s.de

Successful Response (200)

{
  "data": {
    "safe_nr": 5,
    "id": 42
  }
}

Error Response (500)

{
  "message": "Failed to open door"
}

---

Authentication Error Messages

Missing credentials

Status: 401

{
  "message": "Unauthorized"
}

Invalid JWT

Status: 403

{
  "message": "Present token invalid"
}

Invalid API Key

Status: 403

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