library-rest

Borrow a book.

POST/loans

Creates 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

FieldTypeRequiredDescription
bookIdstringyesThe id of the book to borrow. Must currently be available.
userIdstringyesThe id of the user borrowing the book.

Responses

201 The loan was created and the book is now borrowed.

application/json

FieldTypeRequiredDescription
dataobjectyesA single borrow/return transaction linking a Book to a User.
bookIdstringyesThe id of the borrowed Book.
borrowedAtstring (date-time)yesWhen the loan started.
dueAtstring (date-time)yesWhen the book is expected back.
idstringyesUnique identifier assigned by the server, prefixed with ln_.
overduebooleanyesComputed at response time: true if the loan is still open and past its dueAt. Never stored, so it never goes stale.
returnedAtstring (date-time)When the book was actually returned, or null while the loan is still open.
userIdstringyesThe id of the User who borrowed the book.
metaobjectyesResponse metadata attached to every successful response.
requestIdstringyesCorrelation id for this request, echoed from the X-Request-Id request header or generated if absent. Useful for tracing a request across logs.
totalintegerTotal number of matches before pagination was applied. Present only on paginated list responses (currently GET /books).

Errors

CodeMessageDescription
400The request body is not valid JSON.
401The request is missing a valid Authorization: Bearer <token> header.
404bookId or userId does not reference an existing record.
409The book is already out on an open loan.
415The request has a body but its Content-Type is not application/json.
500An 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
  }
}