library-rest

Return a borrowed book.

POST/loans/{id}/return

Closes the loan with the given id, stamping returnedAt with the current time, and flips the book's status back to available. Takes no request body.

Parameters

NameInTypeRequiredDescription
idpathstringyesThe loan's unique identifier.

Responses

200 The loan was closed and the book is now available again.

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
401The request is missing a valid Authorization: Bearer <token> header.
404No resource exists with the given id.
409The loan has already been closed.
500An unexpected error occurred. The response never leaks internal error details.

Response example

{
  "data": {
    "bookId": "bookId_739",
    "borrowedAt": "borrowedAt_703",
    "dueAt": "dueAt_979",
    "id": "id_635",
    "overdue": true,
    "returnedAt": "returnedAt_965",
    "userId": "userId_924"
  },
  "meta": {
    "requestId": "requestId_761",
    "total": 324
  }
}