library-rest

Create a new book.

POST/books

Creates a book in available status and links it to its author. The server assigns the id, createdAt and updatedAt fields.

Request body

application/json

FieldTypeRequiredDescription
authorIdstringyesThe id of an existing Author who wrote this book.
isbnstringyesThe book's ISBN. Must be unique across the catalog.
publishedYearintegeryesThe year the book was first published. Must be between 1450 and next year.
titlestringyesThe book's display title, 1–200 characters.

Responses

201 The book was created.

application/json

FieldTypeRequiredDescription
dataobjectyesA single library title.
authorIdstringyesThe id of the Author who wrote this book.
createdAtstring (date-time)yesWhen the book record was created.
idstringyesUnique identifier assigned by the server, prefixed with bk_.
isbnstringyesThe book's ISBN. Must be unique across the catalog.
publishedYearintegeryesThe year the book was first published. Must be between 1450 and next year.
statusstringyesA book's availability. borrowed means it is out on an open loan. Allowed values: available, borrowed
titlestringyesThe book's display title, 1–200 characters.
updatedAtstring (date-time)yesWhen the book record was last modified.
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.
404authorId does not reference an existing author.
409isbn is already used by another book.
415The request has a body but its Content-Type is not application/json.
422A required field is missing/blank, or publishedYear is out of range.
500An unexpected error occurred. The response never leaks internal error details.

Request example

{
  "authorId": "authorId_101",
  "isbn": "isbn_556",
  "publishedYear": 851,
  "title": "title_954"
}

Response example

{
  "data": {
    "authorId": "authorId_85",
    "createdAt": "createdAt_950",
    "id": "id_573",
    "isbn": "isbn_232",
    "publishedYear": 407,
    "status": "available",
    "title": "title_944",
    "updatedAt": "updatedAt_124"
  },
  "meta": {
    "requestId": "requestId_704",
    "total": 830
  }
}