Books

List books

Books you have made, most recently changed first.

Make a book from a collection

Binds a collection into a book: cover, page layout and — unless you say otherwise — the compiled epub, in one call.

{
    "collectionId": "04857llp3g",
    "name": "What We Ate That Year",
    "coverTemplate": "ribbon"
}

• There is no way to assemble a book page by page. The layout rules live in one place, and a second way of expressing them would be a second way of getting them wrong.
• A collection with no recipes in it comes back 422, saying so.
• You can bind a collection somebody shared with you. The book is yours, not theirs.
• With `compile` false the book answers with `needsCompile: true` and downloading it is a 404 until you compile it.

Get a book

One book, with its page count and cover.

Update a book

Rename it, re-credit it, publish it, or point its QR code at a shop. Not the contents — those come from the collection it was bound from.

{
    "name": "What We Ate That Year",
    "author": "The Bird Family",
    "isPublic": true
}

• Renaming does not rebuild the epub. The file keeps the old title inside it until you compile again — `needsCompile` says when that is owed.
• There is no DELETE for books yet.

Delete a book

Moves it to the bin, with the pages arranged in it. Recoverable for 30 days.

• Nothing else goes with it. The recipes and the collections it was built from are untouched — which is why this is allowed where deleting a collection with recipes in it is refused.
• The compiled epub stays on disk until the window closes, so a restored book is downloadable again without a rebuild.
• A book shared with you can be read, never deleted. That comes back 403.

Restore a book

Takes one back out of the bin, with its pages and its cover.

• Past the retention window this answers 404.

Compile a book

Builds the epub from the book's current contents. Synchronous, and slow enough to matter — seconds, not milliseconds.

• Compiling counts as editing, not reading: a viewer cannot trigger it, and it comes back 403 for them.
• A build that fails answers 422 with the reason, rather than 500.
• Check `needsCompile` first. Compiling a book that does not need it costs the same and changes nothing.
• `needsCompile` now tracks the contents too: editing a recipe or a collection inside the book marks it, not only changing the book itself.

Read a book's pages

Every page in reading order, with whether a layout rebuild will replace it.

Place a page

Put a divider, a picture, a note, a single recipe or another collection into a book. A page placed this way survives every later rebuild of the layout.

{
    "type": "divider",
    "heading": "Puddings",
    "position": 4
}

• Fields the type does not render are dropped rather than stored, so a caption cannot end up on a note where nothing will ever show it.
• Anything that is not yours — a photograph, a recipe, a collection — answers 404 rather than 403, the same as one that does not exist.
• The book is left with unpublished changes. Compile it to publish them.

Change or move a page

Edit the words on a page, swap its photograph, or move it somewhere else in the book.

{
    "position": 1
}

Take a page out

Removes it from the book. Nothing else is deleted — a recipe page removed here leaves the recipe alone.

• A generated page can be removed too, and comes back the next time the layout is rebuilt. That is the honest behaviour rather than a refusal.

Download the epub

The compiled file, as application/epub+zip. Not JSON.

• 404 when the book has never been compiled. Compile it first.
• This endpoint always needs a token, published or not. Publishing a book gives it a public web link instead — /b/{id} to read, and a download from there — which is the one to hand to somebody without an account.