You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by ja...@apache.org on 2026/05/03 19:41:18 UTC
(grails-static-website) 01/01: Add grails-rest-library v8 guide
This is an automated email from the ASF dual-hosted git repository.
jamesfredley pushed a commit to branch add-grails-rest-library-v8
in repository https://gitbox.apache.org/repos/asf/grails-static-website.git
commit 1db2c26401f187f461b55826b8a91fae144bbd34
Author: James Fredley <ja...@users.noreply.github.com>
AuthorDate: Sun May 3 15:41:09 2026 -0400
Add grails-rest-library v8 guide
Worked example for a Book + Author REST API on Grails 8: RestfulController-
based CRUD, JSON views (.gson) with HAL-style _links, structured 422
validation responses with stable error codes, bounded pagination
(max hard-capped at 100), URL-prefix versioning under /v1/, and an
all-or-nothing bulk create endpoint.
Companion conf/guides.yml change repoints the existing v3 and v4 entries
from grails-guides/rest-hibernate to grails-guides/grails-rest-library
(rename of the upstream repo). The old grails3, grails4, grails-4, master
branches are preserved on the renamed repo so the historical guides
keep resolving. The grails-guides/rest-mongodb repo is left alone (it
covers a different stack).
The 17 chapters cover:
- Getting Started (whatYouWillBuild, requirements, howto)
- Creating the Application (download via the rest_api forge type)
- Domain Model (Book + Author with realistic constraints, lazy loading
to head off N+1, bootstrap sample data)
- URL Mappings and v1 Versioning (resources mapping + nested collection
routes for bulk create)
- RestfulController with a Hard Page Cap (listAllResources override)
- JSON Views (.gson partial + index + show pattern)
- Structured 422 Validation Responses (stable field/code/message shape)
- Pagination, Sorting, Filtering (max/offset/sort/order)
- All-or-Nothing Bulk Create (transactionStatus.setRollbackOnly)
- URL-Prefix vs Content-Negotiation Versioning
- Running the Application (curl smoke tests for every endpoint)
Verified locally:
./gradlew validateGuides -PvalidationMode=both
[validateGuides] mode=both: 86 guide(s) parsed, 0 SKIP-warned, 0 errors
./gradlew renderGuide_grails_rest_library_8 --rerun-tasks --no-configuration-cache
Renders all 17 chapter HTML pages, no Unresolved directive errors.
The mode=both pass also confirms grails-guides/grails-rest-library
exists on grails3, grails4, and grails8 branches - i.e. the upstream
rename and the new branch are intact.
Assisted-by: claude-code:claude-opus-4-7
---
conf/guides.yml | 59 +++++++++++++++++++++-
.../v8/guide/bootstrapData.adoc | 14 +++++
.../grails-rest-library/v8/guide/bulkCreate.adoc | 15 ++++++
.../grails-rest-library/v8/guide/controllers.adoc | 11 ++++
guides/grails-rest-library/v8/guide/createApp.adoc | 1 +
.../grails-rest-library/v8/guide/domainModel.adoc | 21 ++++++++
guides/grails-rest-library/v8/guide/download.adoc | 9 ++++
.../v8/guide/gettingStarted.adoc | 3 ++
.../v8/guide/helpWithGrails.adoc | 1 +
guides/grails-rest-library/v8/guide/howto.adoc | 11 ++++
guides/grails-rest-library/v8/guide/jsonViews.adoc | 35 +++++++++++++
.../grails-rest-library/v8/guide/pagination.adoc | 51 +++++++++++++++++++
.../grails-rest-library/v8/guide/requirements.adoc | 5 ++
.../v8/guide/runningTheApp.adoc | 40 +++++++++++++++
.../grails-rest-library/v8/guide/urlMappings.adoc | 24 +++++++++
.../grails-rest-library/v8/guide/validation.adoc | 34 +++++++++++++
.../grails-rest-library/v8/guide/versioning.adoc | 14 +++++
.../v8/guide/whatYouWillBuild.adoc | 8 +++
.../controllers/example/AuthorController.groovy | 23 +++++++++
.../controllers/example/BookController.groovy | 55 ++++++++++++++++++++
.../controllers/example/UrlMappings.groovy | 19 +++++++
.../grails-app/domain/example/Author.groovy | 25 +++++++++
.../snippets/grails-app/domain/example/Book.groovy | 23 +++++++++
.../grails-app/init/example/BootStrap.groovy | 44 ++++++++++++++++
.../snippets/grails-app/views/author/_author.gson | 17 +++++++
.../v8/snippets/grails-app/views/author/index.gson | 13 +++++
.../v8/snippets/grails-app/views/author/show.gson | 7 +++
.../v8/snippets/grails-app/views/book/_book.gson | 21 ++++++++
.../v8/snippets/grails-app/views/book/index.gson | 13 +++++
.../v8/snippets/grails-app/views/book/show.gson | 7 +++
30 files changed, 621 insertions(+), 2 deletions(-)
diff --git a/conf/guides.yml b/conf/guides.yml
index 9a0bcf68f2c..444713984ec 100644
--- a/conf/guides.yml
+++ b/conf/guides.yml
@@ -3466,6 +3466,61 @@ guides:
helpWithGrails:
title: Do you need help with Grails?
+ - name: 'grails-rest-library'
+ title: 'A Library REST API with Grails 8'
+ subtitle: 'Build a Book + Author REST API on Grails 8 using RestfulController, JSON views, structured 422 validation responses, bounded pagination, all-or-nothing bulk create, and URL-prefix versioning under /v1/.'
+ authors:
+ - 'James Fredley'
+ category: 'Web Layer'
+ publicationDate: '2026-05-03'
+ versions:
+ '8':
+ sourcePath: guides/grails-rest-library/v8
+ publicationDate: '2026-05-03'
+ tags:
+ - 'rest'
+ - 'rest-api'
+ - 'json-views'
+ - 'gson'
+ - 'restful-controller'
+ - 'gorm'
+ - 'pagination'
+ - 'validation'
+ - 'grails8'
+ sampleRef:
+ repo: 'grails-guides/grails-rest-library'
+ branch: 'grails8'
+ toc:
+ gettingStarted:
+ title: Getting Started
+ whatYouWillBuild: What You Will Build
+ requirements: What You Will Need
+ howto: How to Complete the Guide
+ createApp:
+ title: Creating the Application
+ download: Download a Grails 8 rest_api Starter
+ domainModel:
+ title: The Book and Author Domain Model
+ bootstrapData: Bootstrap Sample Data
+ urlMappings:
+ title: URL Mappings and v1 Versioning
+ controllers:
+ title: RestfulController With a Hard Page Cap
+ jsonViews:
+ title: JSON Views
+ validation:
+ title: Structured 422 Validation Responses
+ pagination:
+ title: Pagination, Sorting, and Filtering
+ bulkCreate:
+ title: All-or-Nothing Bulk Create
+ versioning:
+ title: URL-Prefix vs Content-Negotiation Versioning
+ runningTheApp:
+ title: Running the Application
+ helpWithGrails:
+ title: Do you need help with Grails?
+
- name: 'grails-scheduled'
title: 'Grails + @Scheduled'
subtitle: 'Learn how to use Spring Task Execution and Scheduling to schedule periodic tasks inside your Grails applications'
@@ -4444,7 +4499,7 @@ guides:
- 'gorm'
- 'grails3'
sampleRef:
- repo: 'grails-guides/rest-hibernate'
+ repo: 'grails-guides/grails-rest-library'
branch: 'grails3'
toc:
training:
@@ -4481,7 +4536,7 @@ guides:
- 'gorm'
- 'grails4'
sampleRef:
- repo: 'grails-guides/rest-hibernate'
+ repo: 'grails-guides/grails-rest-library'
branch: 'grails4'
toc:
training:
diff --git a/guides/grails-rest-library/v8/guide/bootstrapData.adoc b/guides/grails-rest-library/v8/guide/bootstrapData.adoc
new file mode 100644
index 00000000000..68b143d8a75
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/bootstrapData.adoc
@@ -0,0 +1,14 @@
+A `BootStrap` class seeds two authors and four books on first startup, but only outside production:
+
+[source,groovy]
+.grails-app/init/example/BootStrap.groovy
+----
+include::../snippets/grails-app/init/example/BootStrap.groovy[]
+----
+
+Two guards keep this safe:
+
+* `Environment.current == Environment.PRODUCTION` early-exit means the seed never runs against a real database.
+* The `Author.count() > 0` check makes the seed idempotent during development - subsequent restarts do not create duplicate rows.
+
+The `@Transactional` annotation on the `init` closure means the four `save(failOnError: true)` calls all commit together or all roll back. Without it, a failure on book 3 would leave books 1 and 2 in the database in a half-loaded state.
diff --git a/guides/grails-rest-library/v8/guide/bulkCreate.adoc b/guides/grails-rest-library/v8/guide/bulkCreate.adoc
new file mode 100644
index 00000000000..fbdaa26e11c
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/bulkCreate.adoc
@@ -0,0 +1,15 @@
+A frequent ask from API consumers is "let me create N records in one round trip". The single `POST /v1/books/bulk` endpoint added in the URL mappings handles it:
+
+[source,bash]
+----
+curl -s -X POST http://localhost:8080/v1/books/bulk \
+ -H 'Content-Type: application/json' \
+ -d '[
+ { "title": "The Two Towers", "isbn": "9780547928203", "pageCount": 416, "publishedOn": "1954-11-11", "author": { "id": 1 } },
+ { "title": "The Return of the King", "isbn": "9780547928197", "pageCount": 432, "publishedOn": "1955-10-20", "author": { "id": 1 } }
+ ]'
+----
+
+The `bulkCreate` action validates every entry first, *then* saves them. If any single book fails validation, the whole transaction rolls back via `transactionStatus.setRollbackOnly()` and the response is a 422 with structured field errors for every failing entry. If all entries validate, the response is a 201 with the persisted bodies.
+
+This is the safest semantic for bulk creates in a typed API: clients never have to deal with "of the ten you sent, six made it through and four did not". They get either all ten or none, with a precise diagnosis on failure.
diff --git a/guides/grails-rest-library/v8/guide/controllers.adoc b/guides/grails-rest-library/v8/guide/controllers.adoc
new file mode 100644
index 00000000000..8d1e26a059b
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/controllers.adoc
@@ -0,0 +1,11 @@
+`AuthorController` extends `grails.rest.RestfulController<Author>`, which provides every action the URL mappings reference (`index`, `show`, `save`, `update`, `patch`, `delete`) for free:
+
+[source,groovy]
+.grails-app/controllers/example/AuthorController.groovy
+----
+include::../snippets/grails-app/controllers/example/AuthorController.groovy[]
+----
+
+`responseFormats = ['json']` restricts every action to negotiate JSON; the legacy XML-by-default behaviour from older Grails versions is gone.
+
+The single override is `listAllResources`. Without it, a `GET /v1/authors?max=99999` would happily return every row in the table. The hard cap (`Math.min(params.int('max', 25), 100)`) bounds the response, with 25 as the default when the client does not pass `max`. `params.offset`, `params.sort`, and `params.order` flow through unchanged so a paginating client gets `?max=25&offset=50&sort=name&order=asc` semantics out of the box.
diff --git a/guides/grails-rest-library/v8/guide/createApp.adoc b/guides/grails-rest-library/v8/guide/createApp.adoc
new file mode 100644
index 00000000000..f939c0a73a1
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/createApp.adoc
@@ -0,0 +1 @@
+Generate a fresh Apache Grails 8 *Rest API* application from link:https://prev-snapshot.grails.org[prev-snapshot.grails.org]. Pick the `rest_api` application type (not `web`); it ships JSON views by default and skips the GSP view layer the regular `web` profile drags along.
diff --git a/guides/grails-rest-library/v8/guide/domainModel.adoc b/guides/grails-rest-library/v8/guide/domainModel.adoc
new file mode 100644
index 00000000000..043289a174a
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/domainModel.adoc
@@ -0,0 +1,21 @@
+Two domain classes model the library. `Author` is independent; `Book` belongs to an `Author`.
+
+[source,groovy]
+.grails-app/domain/example/Author.groovy
+----
+include::../snippets/grails-app/domain/example/Author.groovy[]
+----
+
+[source,groovy]
+.grails-app/domain/example/Book.groovy
+----
+include::../snippets/grails-app/domain/example/Book.groovy[]
+----
+
+A few constraint choices to highlight:
+
+* `name blank: false, maxSize: 255` on Author and `title` on Book reject empty strings and cap database column width, so the rejection is surfaced at validation time, not as a SQL error.
+* `isbn matches: /^(97(8|9))?\d{9}(\d|X)$/` is a soft ISBN-10/13 check. It is intentionally permissive (no checksum validation); the regex is a chapter-and-verse example of how Grails' `matches:` constraint composes with `unique: true`.
+* `pageCount nullable: true, min: 1` allows an unset value but rejects zero or negative integers.
+
+The `static mapping` block on `Author` lazy-loads `books`. With eager loading, every `Author.list()` call would fetch every book of every author - the textbook N+1 problem. Lazy loading delegates to GORM's session lifecycle, and views explicitly opt back in to eager fetch via `Author.list(fetch: [books: 'join'])` when they need it.
diff --git a/guides/grails-rest-library/v8/guide/download.adoc b/guides/grails-rest-library/v8/guide/download.adoc
new file mode 100644
index 00000000000..8e5404730d8
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/download.adoc
@@ -0,0 +1,9 @@
+[source,bash]
+----
+curl -L -o library.zip \
+ "https://prev-snapshot.grails.org/create/rest_api/example.library?lang=GROOVY&build=GRADLE&test=SPOCK&javaVersion=JDK_21&features=postgres,testcontainers,views-json,database-migration"
+unzip library.zip
+cd library
+----
+
+The `rest_api` starter is leaner than the `web` starter: no asset pipeline, no GSP, no Bootstrap webjars. The `views-json` feature adds the `.gson` view support and the matching `org.apache.grails:grails-views-gson` dependency.
diff --git a/guides/grails-rest-library/v8/guide/gettingStarted.adoc b/guides/grails-rest-library/v8/guide/gettingStarted.adoc
new file mode 100644
index 00000000000..3140ba257ea
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/gettingStarted.adoc
@@ -0,0 +1,3 @@
+In this guide you will build a small Library REST API on Apache Grails 8 with two domain classes (`Book` and `Author`), a `RestfulController`-driven CRUD surface, JSON views (`.gson`), and the production-quality concerns most beginner REST guides skip: structured 422 validation responses, bounded pagination, URL-prefix versioning, and an all-or-nothing bulk-create endpoint.
+
+This guide targets Apache Grails 8 / Spring Boot 4 / JDK 21.
diff --git a/guides/grails-rest-library/v8/guide/helpWithGrails.adoc b/guides/grails-rest-library/v8/guide/helpWithGrails.adoc
new file mode 100644
index 00000000000..e062f614b1a
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/helpWithGrails.adoc
@@ -0,0 +1 @@
+include::{commondir}/common-helpWithGrails.adoc[]
diff --git a/guides/grails-rest-library/v8/guide/howto.adoc b/guides/grails-rest-library/v8/guide/howto.adoc
new file mode 100644
index 00000000000..1fc06895855
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/howto.adoc
@@ -0,0 +1,11 @@
+You can either type the code in this guide as you read or skip ahead and clone the finished sample:
+
+[source,bash]
+----
+git clone -b grails8 https://github.com/grails-guides/grails-rest-library.git
+cd grails-rest-library/complete
+./gradlew bootRun
+curl -s http://localhost:8080/v1/books | jq
+----
+
+`initial/` is the vanilla Grails 8 `rest_api` starter from `https://prev-snapshot.grails.org` (with the `postgres`, `testcontainers`, `views-json`, and `database-migration` features). `complete/` adds the Book + Author domain model, the controllers, the JSON views, and the bootstrap data.
diff --git a/guides/grails-rest-library/v8/guide/jsonViews.adoc b/guides/grails-rest-library/v8/guide/jsonViews.adoc
new file mode 100644
index 00000000000..3bc0311eea8
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/jsonViews.adoc
@@ -0,0 +1,35 @@
+JSON views (`.gson`) shape the response without touching the controller. Each view declares its model and emits the JSON body using a Groovy DSL.
+
+The shared partial:
+
+[source,groovy]
+.grails-app/views/book/_book.gson
+----
+include::../snippets/grails-app/views/book/_book.gson[]
+----
+
+The `model { }` block declares the Groovy types the view expects. The `json { }` block emits the response body. The `_links` object is plain JSON; nothing about HAL or HATEOAS is enforced - it is a convention you can either keep or drop, but having it makes API discovery from a browser dramatically easier.
+
+The list view reuses the partial via `g.render`:
+
+[source,groovy]
+.grails-app/views/book/index.gson
+----
+include::../snippets/grails-app/views/book/index.gson[]
+----
+
+Three things to notice:
+
+* The `model` block declares both the page (`Iterable<Book> bookList`) and the total count (`Long bookCount`). `RestfulController.index` populates both automatically.
+* The pagination metadata at the top (`page`, `pageSize`, `total`) gives clients enough information to render a pager without re-querying.
+* `bookList.collect { Book b -> g.render(template: 'book', model: [book: b]) }` reuses the `_book.gson` partial for every item. One source of truth for the body shape; both the show and index views use it.
+
+The `show.gson` view is a one-liner that delegates to the same partial:
+
+[source,groovy]
+.grails-app/views/book/show.gson
+----
+include::../snippets/grails-app/views/book/show.gson[]
+----
+
+Author views follow the same pattern: `_author.gson` partial, `index.gson` list with pagination metadata, `show.gson` one-liner.
diff --git a/guides/grails-rest-library/v8/guide/pagination.adoc b/guides/grails-rest-library/v8/guide/pagination.adoc
new file mode 100644
index 00000000000..9b57a4db55a
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/pagination.adoc
@@ -0,0 +1,51 @@
+Every list endpoint in this guide exposes the same three query parameters:
+
+* `max` - page size, default 25, hard-capped at 100.
+* `offset` - zero-based starting offset, default 0.
+* `sort` - column name to sort by, with optional `order=asc` or `order=desc`.
+
+`RestfulController.index` reads `params.max` and `params.offset` automatically; the override on `listAllResources` we already wrote bounds them.
+
+Round-trip with `curl`:
+
+[source,bash]
+----
+curl -s 'http://localhost:8080/v1/books?max=2&offset=2&sort=publishedOn&order=desc' | jq
+----
+
+Returns:
+
+[source,json]
+----
+{
+ "page": 1,
+ "pageSize": 2,
+ "total": 4,
+ "items": [
+ { "id": 2, "title": "The Fellowship of the Ring", ... },
+ { "id": 1, "title": "The Hobbit", ... }
+ ]
+}
+----
+
+The `page` value is `offset / pageSize`; `total` is the unpaginated row count. A client that wants a page-and-size API instead of an offset-and-size API can compute either from the other.
+
+[TIP]
+====
+*Filtering* sits orthogonal to pagination. If you want `GET /v1/books?author=2`, override `listAllResources` to consume `params.author`:
+
+[source,groovy]
+----
+@Override
+protected List<Book> listAllResources(Map params) {
+ params.max = Math.min(params.int('max', 25), 100)
+ if (params.author) {
+ Book.findAllByAuthor(Author.get(params.long('author')), params)
+ } else {
+ Book.list(params)
+ }
+}
+----
+
+This stays out of the URL mappings layer; the same route serves both filtered and unfiltered queries.
+====
diff --git a/guides/grails-rest-library/v8/guide/requirements.adoc b/guides/grails-rest-library/v8/guide/requirements.adoc
new file mode 100644
index 00000000000..388220a38d1
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/requirements.adoc
@@ -0,0 +1,5 @@
+To complete this guide you will need:
+
+* JDK 21
+* About 30 minutes
+* `curl` or another HTTP client for hitting the running endpoints
diff --git a/guides/grails-rest-library/v8/guide/runningTheApp.adoc b/guides/grails-rest-library/v8/guide/runningTheApp.adoc
new file mode 100644
index 00000000000..35c4e59b834
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/runningTheApp.adoc
@@ -0,0 +1,40 @@
+With everything in place, run the app:
+
+[source,bash]
+----
+./gradlew bootRun
+----
+
+The bootstrap data populates two authors and four books on first start. Smoke-test the surface:
+
+[source,bash]
+----
+# List
+curl -s http://localhost:8080/v1/books | jq
+curl -s http://localhost:8080/v1/authors | jq
+
+# Show single
+curl -s http://localhost:8080/v1/books/1 | jq
+
+# Pagination
+curl -s 'http://localhost:8080/v1/books?max=2&offset=2&sort=title' | jq
+
+# Create
+curl -s -X POST http://localhost:8080/v1/books \
+ -H 'Content-Type: application/json' \
+ -d '{ "title": "The Silmarillion", "isbn": "9780544338012", "pageCount": 384, "author": { "id": 1 } }' | jq
+
+# Validation failure (422 with structured field errors)
+curl -s -X POST http://localhost:8080/v1/books \
+ -H 'Content-Type: application/json' \
+ -d '{ "title": "" }' | jq
+
+# Bulk create (all-or-nothing)
+curl -s -X POST http://localhost:8080/v1/books/bulk \
+ -H 'Content-Type: application/json' \
+ -d '[
+ { "title": "The Two Towers", "isbn": "9780547928203", "pageCount": 416, "author": { "id": 1 } }
+ ]' | jq
+----
+
+Each of these returns a sensible JSON body with the right HTTP status. The validation-failure curl returns 422 with the structured field errors from the validation chapter; the rest return 200 (list/show), 201 (create), or 204 (delete) as appropriate.
diff --git a/guides/grails-rest-library/v8/guide/urlMappings.adoc b/guides/grails-rest-library/v8/guide/urlMappings.adoc
new file mode 100644
index 00000000000..8c13e85b689
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/urlMappings.adoc
@@ -0,0 +1,24 @@
+URL-prefix versioning lives in `UrlMappings.groovy`:
+
+[source,groovy]
+.grails-app/controllers/example/UrlMappings.groovy
+----
+include::../snippets/grails-app/controllers/example/UrlMappings.groovy[]
+----
+
+The `'/v1/books'(resources: 'book')` line generates the standard seven REST routes:
+
+[cols="1,4,3"]
+|===
+| Method | Path | Controller action
+
+| GET | `/v1/books` | `index`
+| POST | `/v1/books` | `save`
+| GET | `/v1/books/{id}` | `show`
+| PUT | `/v1/books/{id}` | `update`
+| PATCH | `/v1/books/{id}` | `patch`
+| DELETE | `/v1/books/{id}` | `delete`
+| GET | `/v1/books/create` | `create` (rarely used in JSON APIs; safe to ignore)
+|===
+
+The nested `collection { ... }` block adds non-instance routes - in our case `POST /v1/books/bulk` mapped to a `bulkCreate` action we will write later.
diff --git a/guides/grails-rest-library/v8/guide/validation.adoc b/guides/grails-rest-library/v8/guide/validation.adoc
new file mode 100644
index 00000000000..9b72ab21bce
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/validation.adoc
@@ -0,0 +1,34 @@
+When a `POST /v1/books` body fails validation, `RestfulController` returns a 422 by default - but the body shape is not always what API consumers expect. The hand-rolled `bulkCreate` action in `BookController` shows the structured-422 pattern:
+
+[source,groovy]
+.grails-app/controllers/example/BookController.groovy
+----
+include::../snippets/grails-app/controllers/example/BookController.groovy[]
+----
+
+When validation fails, the body looks like:
+
+[source,json]
+----
+{
+ "books": [
+ {
+ "index": 0,
+ "errors": [
+ { "field": "title", "code": "blank", "message": "Property [title] of class [Book] cannot be blank" },
+ { "field": "isbn", "code": "matches", "message": "Property [isbn] of class [Book] does not match the required pattern" }
+ ]
+ },
+ {
+ "index": 2,
+ "errors": [
+ { "field": "isbn", "code": "unique", "message": "Property [isbn] of class [Book] with value [9780547928227] must be unique" }
+ ]
+ }
+ ]
+}
+----
+
+The shape is opinionated: each failing object has its source-array `index` so the client can map the failure back to the input, and each error has a stable `code` (`blank`, `matches`, `unique`, `nullable`, `min`, `max`) the client can branch on without parsing free-text messages. Any client building a form on top of this API can light up the right field with the right error without string-matching.
+
+The `transactionStatus.setRollbackOnly()` line is what makes `bulkCreate` all-or-nothing: even though the action's `@Transactional` started a transaction implicitly, this call marks it for rollback regardless of what the action returns. The four books that *did* validate never reach the database.
diff --git a/guides/grails-rest-library/v8/guide/versioning.adoc b/guides/grails-rest-library/v8/guide/versioning.adoc
new file mode 100644
index 00000000000..0c0755c855b
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/versioning.adoc
@@ -0,0 +1,14 @@
+Two patterns dominate REST versioning:
+
+* *URL prefix*: `/v1/books`, `/v2/books`. Cheap to implement, trivially debuggable, plays well with caches and proxies.
+* *Content negotiation*: `Accept: application/vnd.example.v2+json`. Cleaner semantically (the URL is the resource, not the representation), but adds friction to every consumer.
+
+This guide leads with URL prefix because it is the cheaper choice for a project that has not yet shipped its first breaking change. The `'/v1/books'(resources: 'book')` URL mapping localises every v1 route under a single prefix; when v2 ships, you add a second `'/v2/books'(resources: 'bookV2')` mapping to a fresh `BookV2Controller` and let v1 keep serving its existing clients while you migrate them.
+
+The migration discipline that *does* matter:
+
+* *Never break v1 within its lifetime.* Even adding a new required field is a breaking change for a strict client. Add fields as optional; deprecate via response headers.
+* *Document a deprecation timeline* on day 1 of v2. "v1 sunsets 12 months after v2 GA" gives consumers a window.
+* *Run v1 and v2 from the same codebase* whenever you can. Two controllers, two view trees, one domain model. Forking the domain model is a smell.
+
+For the small percentage of cases where content negotiation makes sense - public APIs with thousands of consumers, where ~/v1~ in URLs would be visually offensive - Grails' `responseFormats` and the `Accept`-header mapping are first-class. The mechanics are the same; only the surface changes.
diff --git a/guides/grails-rest-library/v8/guide/whatYouWillBuild.adoc b/guides/grails-rest-library/v8/guide/whatYouWillBuild.adoc
new file mode 100644
index 00000000000..bc5f884261d
--- /dev/null
+++ b/guides/grails-rest-library/v8/guide/whatYouWillBuild.adoc
@@ -0,0 +1,8 @@
+By the end of the guide you will have:
+
+* A `Book` and `Author` domain pair, with `Book` `belongsTo: Author` and reasonable constraints (a regex-validated ISBN, a positive `pageCount`, optional `dateOfBirth`).
+* `BookController extends RestfulController<Book>` and `AuthorController extends RestfulController<Author>`, each scoped to JSON via `responseFormats` and bounded by a `listAllResources` override that hard-caps `params.max` at 100.
+* JSON views (`.gson`) under `grails-app/views/book/` and `grails-app/views/author/` that render the API responses. Each view emits a body, embeds a HAL-style `_links` object, and reuses a shared `_book.gson` / `_author.gson` partial.
+* A `POST /v1/books/bulk` endpoint that accepts a JSON array, validates every entry, and returns a structured 422 with the field errors of every failing entry on the first validation failure (the whole transaction rolls back).
+* URL-prefix versioning: every endpoint lives under `/v1/`. The chapter on versioning compares this with the `Accept: application/vnd.example.v2+json` content-negotiation approach and recommends starting with URL prefixes.
+* Sample data in `BootStrap` so `curl http://localhost:8080/v1/books` returns four real books from two real authors immediately after `./gradlew bootRun`.
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/AuthorController.groovy b/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/AuthorController.groovy
new file mode 100644
index 00000000000..3c51d83e3b8
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/AuthorController.groovy
@@ -0,0 +1,23 @@
+package example
+
+import grails.rest.RestfulController
+
+class AuthorController extends RestfulController<Author> {
+
+ static responseFormats = ['json']
+
+ AuthorController() { super(Author) }
+
+ /**
+ * GET /v1/authors?max=20&offset=0&sort=name&order=asc
+ *
+ * Bound `max` defaults to 25 and is hard-capped at 100 so a paginating
+ * client cannot ask for the full table in one request. `offset`,
+ * `sort`, and `order` flow through to the GORM query unchanged.
+ */
+ @Override
+ protected List<Author> listAllResources(Map params) {
+ params.max = Math.min(params.int('max', 25), 100)
+ Author.list(params)
+ }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/BookController.groovy b/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/BookController.groovy
new file mode 100644
index 00000000000..c5957679782
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/BookController.groovy
@@ -0,0 +1,55 @@
+package example
+
+import grails.gorm.transactions.Transactional
+import grails.rest.RestfulController
+import org.springframework.http.HttpStatus
+
+class BookController extends RestfulController<Book> {
+
+ static responseFormats = ['json']
+
+ BookController() { super(Book) }
+
+ @Override
+ protected List<Book> listAllResources(Map params) {
+ params.max = Math.min(params.int('max', 25), 100)
+ Book.list(params)
+ }
+
+ /**
+ * POST /v1/books/bulk
+ *
+ * All-or-nothing bulk create. The whole request rolls back on the
+ * first validation failure; the response is a structured 422 with
+ * the field errors of every failing book in the batch.
+ */
+ @Transactional
+ def bulkCreate() {
+ if (!request.JSON instanceof List) {
+ response.status = HttpStatus.UNPROCESSABLE_ENTITY.value()
+ respond errors: [[message: 'request body must be a JSON array of Book objects']]
+ return
+ }
+
+ List<Book> drafts = request.JSON.collect { json -> new Book(json as Map) }
+ List<Map> failures = []
+ drafts.eachWithIndex { Book b, int i ->
+ if (!b.validate()) {
+ failures << [index: i, errors: b.errors.fieldErrors.collect {
+ [field: it.field, code: it.code, message: it.defaultMessage]
+ }]
+ }
+ }
+
+ if (failures) {
+ transactionStatus.setRollbackOnly()
+ response.status = HttpStatus.UNPROCESSABLE_ENTITY.value()
+ respond books: failures
+ return
+ }
+
+ drafts*.save(flush: true)
+ response.status = HttpStatus.CREATED.value()
+ respond books: drafts
+ }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/UrlMappings.groovy b/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/UrlMappings.groovy
new file mode 100644
index 00000000000..928225125ff
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/controllers/example/UrlMappings.groovy
@@ -0,0 +1,19 @@
+package example
+
+class UrlMappings {
+
+ static mappings = {
+
+ '/v1/books'(resources: 'book') {
+ collection {
+ '/bulk'(controller: 'book', action: 'bulkCreate', method: 'POST')
+ }
+ }
+ '/v1/authors'(resources: 'author')
+
+ '/'(view: '/index')
+
+ '500'(view: '/error')
+ '404'(view: '/notFound')
+ }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/domain/example/Author.groovy b/guides/grails-rest-library/v8/snippets/grails-app/domain/example/Author.groovy
new file mode 100644
index 00000000000..274de2d48dc
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/domain/example/Author.groovy
@@ -0,0 +1,25 @@
+package example
+
+import grails.persistence.Entity
+
+@Entity
+class Author {
+
+ String name
+ String biography
+ Date dateOfBirth
+
+ static hasMany = [books: Book]
+
+ static constraints = {
+ name blank: false, maxSize: 255
+ biography nullable: true, maxSize: 4000
+ dateOfBirth nullable: true
+ }
+
+ static mapping = {
+ books fetch: 'lazy'
+ }
+
+ String toString() { name }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/domain/example/Book.groovy b/guides/grails-rest-library/v8/snippets/grails-app/domain/example/Book.groovy
new file mode 100644
index 00000000000..3547c7ccf00
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/domain/example/Book.groovy
@@ -0,0 +1,23 @@
+package example
+
+import grails.persistence.Entity
+
+@Entity
+class Book {
+
+ String title
+ String isbn
+ Integer pageCount
+ Date publishedOn
+
+ static belongsTo = [author: Author]
+
+ static constraints = {
+ title blank: false, maxSize: 255
+ isbn blank: false, unique: true, matches: /^(97(8|9))?\d{9}(\d|X)$/
+ pageCount nullable: true, min: 1
+ publishedOn nullable: true
+ }
+
+ String toString() { title }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/init/example/BootStrap.groovy b/guides/grails-rest-library/v8/snippets/grails-app/init/example/BootStrap.groovy
new file mode 100644
index 00000000000..4e231fb0db0
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/init/example/BootStrap.groovy
@@ -0,0 +1,44 @@
+package example
+
+import grails.gorm.transactions.Transactional
+import grails.util.Environment
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
+
+class BootStrap {
+
+ private static final Logger log = LoggerFactory.getLogger(BootStrap)
+
+ @Transactional
+ Closure init = { servletContext ->
+
+ if (Environment.current == Environment.PRODUCTION) {
+ log.info 'production environment - skipping bootstrap data'
+ return
+ }
+ if (Author.count() > 0) {
+ log.info 'authors already present - skipping bootstrap data'
+ return
+ }
+
+ Author tolkien = new Author(name: 'J.R.R. Tolkien',
+ biography: 'English writer and philologist (1892-1973).',
+ dateOfBirth: Date.parse('yyyy-MM-dd', '1892-01-03'))
+ .save(failOnError: true)
+ Author leguin = new Author(name: 'Ursula K. Le Guin',
+ biography: 'American author (1929-2018).',
+ dateOfBirth: Date.parse('yyyy-MM-dd', '1929-10-21'))
+ .save(failOnError: true)
+
+ new Book(author: tolkien, title: 'The Hobbit', isbn: '9780547928227', pageCount: 310,
+ publishedOn: Date.parse('yyyy-MM-dd', '1937-09-21')).save(failOnError: true)
+ new Book(author: tolkien, title: 'The Fellowship of the Ring', isbn: '9780547928210', pageCount: 423,
+ publishedOn: Date.parse('yyyy-MM-dd', '1954-07-29')).save(failOnError: true)
+ new Book(author: leguin, title: 'A Wizard of Earthsea', isbn: '9780547851402', pageCount: 205,
+ publishedOn: Date.parse('yyyy-MM-dd', '1968-11-01')).save(failOnError: true)
+ new Book(author: leguin, title: 'The Left Hand of Darkness', isbn: '9780441478125', pageCount: 304,
+ publishedOn: Date.parse('yyyy-MM-dd', '1969-03-01')).save(failOnError: true)
+ }
+
+ Closure destroy = { }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/views/author/_author.gson b/guides/grails-rest-library/v8/snippets/grails-app/views/author/_author.gson
new file mode 100644
index 00000000000..ac96c7b2d78
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/views/author/_author.gson
@@ -0,0 +1,17 @@
+import example.Author
+
+model {
+ Author author
+}
+
+json {
+ id author.id
+ name author.name
+ biography author.biography
+ dateOfBirth author.dateOfBirth?.format('yyyy-MM-dd')
+ bookCount author.books?.size() ?: 0
+ _links {
+ self url: g.createLink(controller: 'author', action: 'show', id: author.id, absolute: true)
+ books url: g.createLink(controller: 'book', action: 'index', params: [author: author.id], absolute: true)
+ }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/views/author/index.gson b/guides/grails-rest-library/v8/snippets/grails-app/views/author/index.gson
new file mode 100644
index 00000000000..c8b2fbc0f6d
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/views/author/index.gson
@@ -0,0 +1,13 @@
+import example.Author
+
+model {
+ Iterable<Author> authorList
+ Long authorCount
+}
+
+json {
+ page Math.max(0, (params.int('offset', 0) ?: 0).intdiv(params.int('max', 25) ?: 25))
+ pageSize params.int('max', 25)
+ total authorCount
+ items authorList.collect { Author a -> g.render(template: 'author', model: [author: a]) }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/views/author/show.gson b/guides/grails-rest-library/v8/snippets/grails-app/views/author/show.gson
new file mode 100644
index 00000000000..59a0eb0bcc6
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/views/author/show.gson
@@ -0,0 +1,7 @@
+import example.Author
+
+model {
+ Author author
+}
+
+json g.render(template: 'author', model: [author: author])
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/views/book/_book.gson b/guides/grails-rest-library/v8/snippets/grails-app/views/book/_book.gson
new file mode 100644
index 00000000000..28e7cf9d683
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/views/book/_book.gson
@@ -0,0 +1,21 @@
+import example.Book
+
+model {
+ Book book
+}
+
+json {
+ id book.id
+ title book.title
+ isbn book.isbn
+ pageCount book.pageCount
+ publishedOn book.publishedOn?.format('yyyy-MM-dd')
+ author {
+ id book.author.id
+ name book.author.name
+ }
+ _links {
+ self url: g.createLink(controller: 'book', action: 'show', id: book.id, absolute: true)
+ author url: g.createLink(controller: 'author', action: 'show', id: book.author.id, absolute: true)
+ }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/views/book/index.gson b/guides/grails-rest-library/v8/snippets/grails-app/views/book/index.gson
new file mode 100644
index 00000000000..763066abd96
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/views/book/index.gson
@@ -0,0 +1,13 @@
+import example.Book
+
+model {
+ Iterable<Book> bookList
+ Long bookCount
+}
+
+json {
+ page Math.max(0, (params.int('offset', 0) ?: 0).intdiv(params.int('max', 25) ?: 25))
+ pageSize params.int('max', 25)
+ total bookCount
+ items bookList.collect { Book b -> g.render(template: 'book', model: [book: b]) }
+}
diff --git a/guides/grails-rest-library/v8/snippets/grails-app/views/book/show.gson b/guides/grails-rest-library/v8/snippets/grails-app/views/book/show.gson
new file mode 100644
index 00000000000..fa61f6c25fc
--- /dev/null
+++ b/guides/grails-rest-library/v8/snippets/grails-app/views/book/show.gson
@@ -0,0 +1,7 @@
+import example.Book
+
+model {
+ Book book
+}
+
+json g.render(template: 'book', model: [book: book])