library-rest
Borrow a book.
POST
/loansCreates a new loan for bookId and userId, due back 14 days from now, and flips the book's status to borrowed. As with a real library, a book that is already out on loan cannot be borrowed again until it is returned.
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
| bookId | string | yes | The id of the book to borrow. Must currently be available. |
| userId | string | yes | The id of the user borrowing the book. |
Responses
201 The loan was created and the book is now borrowed.
application/json
| Field | Type | Required | Description |
|---|---|---|---|
| data | object | yes | A single borrow/return transaction linking a Book to a User. |
| bookId | string | yes | The id of the borrowed Book. |
| borrowedAt | string (date-time) | yes | When the loan started. |
| dueAt | string (date-time) | yes | When the book is expected back. |
| id | string | yes | Unique identifier assigned by the server, prefixed with ln_. |
| overdue | boolean | yes | Computed at response time: true if the loan is still open and past its dueAt. Never stored, so it never goes stale. |
| returnedAt | string (date-time) | When the book was actually returned, or null while the loan is still open. | |
| userId | string | yes | The id of the User who borrowed the book. |
| meta | object | yes | Response metadata attached to every successful response. |
| requestId | string | yes | Correlation id for this request, echoed from the X-Request-Id request header or generated if absent. Useful for tracing a request across logs. |
| total | integer | Total number of matches before pagination was applied. Present only on paginated list responses (currently GET /books). |
Errors
| Code | Message | Description |
|---|---|---|
| 400 | The request body is not valid JSON. | |
| 401 | The request is missing a valid Authorization: Bearer <token> header. | |
| 404 | bookId or userId does not reference an existing record. | |
| 409 | The book is already out on an open loan. | |
| 415 | The request has a body but its Content-Type is not application/json. | |
| 500 | An unexpected error occurred. The response never leaks internal error details. |
Request example
{
"bookId": "bookId_528",
"userId": "userId_981"
}Response example
{
"data": {
"bookId": "bookId_476",
"borrowedAt": "borrowedAt_313",
"dueAt": "dueAt_207",
"id": "id_186",
"overdue": true,
"returnedAt": "returnedAt_288",
"userId": "userId_396"
},
"meta": {
"requestId": "requestId_643",
"total": 814
}
}