Add grails-rest-library v8 guide (rename of rest-hibernate)#496
Merged
jamesfredley merged 1 commit intomasterfrom May 3, 2026
Merged
Add grails-rest-library v8 guide (rename of rest-hibernate)#496jamesfredley merged 1 commit intomasterfrom
jamesfredley merged 1 commit intomasterfrom
Conversation
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
This was referenced May 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the A Library REST API with Grails 8 guide as the fifth Grails 8 sample-app-flavour guide, following PRs #479, #493, #494, #495.
A worked Book + Author REST API focused on the production-quality concerns most beginner REST guides skip: structured 422 validation responses with stable codes, bounded pagination (page size hard-capped at 100), all-or-nothing bulk create, URL-prefix versioning under
/v1/, and HAL-style_linksin the JSON views.Companion conf/guides.yml change (rename of upstream repo)
The upstream repo
grails-guides/rest-hibernatewas renamed tograils-guides/grails-rest-libraryto match the sharper topic of the new guide. GitHub auto-redirects keep historical clones working; this PR repoints both v3 and v4sampleRef.repolines (lines 4447 and 4484) at the new canonical name. The originalgrails3,grails4,grails-4, andmasterbranches are preserved on the renamed repo so the historical guides continue to resolve. Thegrails-guides/rest-mongodbrepo is left alone - it covers a different stack and is not in scope.What's in the PR
conf/guides.yml- newgrails-rest-libraryregistry entry plus the two repo-name updates on the existing v3 and v4 entries.guides/grails-rest-library/v8/guide/*.adoc- 17 chapters.guides/grails-rest-library/v8/snippets/- vendored Author + Book domains, UrlMappings, AuthorController + BookController, six.gsonviews (paired_partial.gson+index.gson+show.gson), and BootStrap.Upstream sample app
grails-guides/grails-rest-libraryon thegrails8branch contains the standardinitial/+complete/layout.initial/is the vanilla forge output (rest_apitype withpostgres,testcontainers,views-json,database-migrationfeatures).complete/adds the Library API layer.Verification
./gradlew validateGuides -PvalidationMode=bothreturns 86 guides, 0 errors../gradlew renderGuide_grails_rest_library_8 --rerun-tasks --no-configuration-cacherenders all 17 chapter HTML pages, no Unresolved directive errors.Notes for reviewers
grails-guides/*repo to a sharper name (after the Tailwind, Docker, and CI/CD PRs). Same pattern: GitHub auto-redirects,conf/guides.ymlrepointed, original branches preserved.transactionStatus.setRollbackOnly()so the failing-batch case really does roll back every persisted entry; it is the safest semantic for a typed API./v1/) and recommends starting there; content negotiation is mentioned but not the primary recipe.