json-rest-api 1.0.28 → 2.0.0

package/docs/GUIDE/08-many-to-many.md

@@ -0,0 +1,184 @@
+---
+title: "Many-to-many relationships"
+chapter: 8
+chapter_label: "08"
+---
+
+# 08. Many-to-many relationships
+
+Books can have several authors, and authors can write several books. A pivot
+resource, `book_authors`, represents each connection and can also hold attributes
+such as a contribution role. Declare that resource alongside the two endpoints.
+
+Insert the following blocks in order into the [starting script](03-running-example.md)
+with a fresh database, before the HTTP server starts. This chapter uses
+`RestApiKnexPlugin` and ordinary pivot rows. Canonical storage keeps membership
+in separate tenant-scoped links: direct pivot resource rows and their metadata
+do not create or describe those links. The relationship-read/write API remains
+available there, but the direct pivot examples below apply to table-backed storage.
+
+## Define the resources
+
+```javascript
+await api.addResource('books', {
+  schema: { title: { type: 'string', required: true, indexed: true } },
+  relationships: {
+    authors: { type: 'manyToMany', through: 'book_authors', foreignKey: 'book_id', otherKey: 'author_id' }
+  },
+  searchSchema: {
+    authorName: { type: 'string', actualField: 'authors.name', filterOperator: 'contains' }
+  }
+})
+await api.addResource('authors', {
+  schema: { name: { type: 'string', required: true, indexed: true } },
+  relationships: {
+    books: { type: 'manyToMany', through: 'book_authors', foreignKey: 'author_id', otherKey: 'book_id' }
+  },
+  searchSchema: {
+    bookTitle: { type: 'string', actualField: 'books.title', filterOperator: 'contains' }
+  }
+})
+await api.addResource('book_authors', {
+  schema: {
+    book_id: { type: 'id', belongsTo: 'books', as: 'book', required: true },
+    author_id: { type: 'id', belongsTo: 'authors', as: 'author', required: true },
+    contribution: { type: 'string', nullable: true }
+  },
+  searchSchema: { book: { type: 'id', actualField: 'book_id' } }
+})
+await api.resources.books.createKnexTable()
+await api.resources.authors.createKnexTable()
+await api.resources.book_authors.createKnexTable()
+```
+
+`through` names the pivot resource. `foreignKey` is its logical field pointing
+to the current resource, and `otherKey` points to the related resource. The
+reverse declaration swaps these fields. Storage mapping determines physical
+columns. Each pivot record has its own resource ID.
+
+## Create records with membership
+
+```javascript
+const neil = await api.resources.authors.post({ data: { name: 'Neil Gaiman' } })
+const terry = await api.resources.authors.post({ data: { name: 'Terry Pratchett' } })
+const goodOmens = await api.resources.books.post({
+  data: { title: 'Good Omens', authors: [neil.id, terry.id] }
+})
+const americanGods = await api.resources.books.post({
+  format: 'jsonapi',
+  document: {
+    data: {
+      type: 'books',
+      attributes: { title: 'American Gods' },
+      relationships: { authors: { data: [{ type: 'authors', id: neil.id }] } }
+    }
+  }
+})
+```
+
+The plain record uses an ID array under `data.authors`; JSON:API uses
+identifier linkage under `data.relationships.authors.data`. These operations
+create the necessary pivot connections. Do not also create direct pivot records
+for those same connections.
+
+## Read includes and filter through the pivot
+
+```javascript
+const includedBook = await api.resources.books.get({
+  id: goodOmens.id, queryParams: { include: ['authors'] }
+})
+const includedDocument = await api.resources.books.get({
+  id: goodOmens.id, format: 'jsonapi', queryParams: { include: ['authors'] }
+})
+const booksByNeil = await api.resources.books.query({
+  queryParams: { filters: { authorName: 'Neil' }, include: ['authors'] }
+})
+const authorsOfGods = await api.resources.authors.query({
+  queryParams: { filters: { bookTitle: 'Gods' } }
+})
+console.log('Good Omens authors:', includedBook.authors)
+console.log('JSON:API authors:', includedDocument.included)
+console.log('Books by Neil:', booksByNeil.data)
+console.log('Authors of Gods:', authorsOfGods.data)
+```
+
+Good Omens includes both authors. Plain responses embed included records;
+JSON:API retains relationship identifiers and places related records in
+`included`. Without an include, membership is represented by IDs rather than
+full author attributes. The filter finds both books by Neil; its Good Omens
+result still includes Terry as well. Filtering a parent does not filter the
+included collection to just matching children. The reverse title filter finds
+Neil alone.
+
+## Work with pivot attributes directly
+
+```javascript
+const colorOfMagic = await api.resources.books.post({
+  data: { title: 'The Color of Magic' }
+})
+const contribution = await api.resources.book_authors.post({
+  data: { book: colorOfMagic.id, author: terry.id, contribution: 'primary' }
+})
+const omensPivots = await api.resources.book_authors.query({
+  queryParams: { filters: { book: goodOmens.id } }
+})
+for (const pivot of omensPivots.data) {
+  await api.resources.book_authors.patch({
+    id: pivot.id, data: { contribution: 'co-author' }, returning: 'none'
+  })
+}
+const updatedPivots = await api.resources.book_authors.query({
+  queryParams: { filters: { book: goodOmens.id } }
+})
+console.log('Direct pivot:', contribution)
+console.log('Updated contributions:', updatedPivots.data)
+```
+
+The pivot is a resource: use its public relationship aliases `book` and `author`
+in `data`. Its declared `book` filter finds the two Good Omens connection
+records. Updating their attributes changes contribution metadata without
+replacing membership. Query the pivot resource to retrieve these attributes;
+a book's author include does not automatically attach pivot attributes to authors.
+Direct pivot creation should not duplicate membership already created through
+`authors`. Define the uniqueness constraints your persistent schema requires.
+
+## Remove membership without deleting an author
+
+```javascript
+await api.resources.books.deleteRelationship({
+  id: goodOmens.id,
+  relationshipName: 'authors',
+  relationshipData: [{ type: 'authors', id: terry.id }]
+})
+const remainingMembers = await api.resources.books.getRelationship({
+  id: goodOmens.id, relationshipName: 'authors'
+})
+const remainingPivots = await api.resources.book_authors.query({
+  queryParams: { filters: { book: goodOmens.id } }
+})
+const terryStillExists = await api.resources.authors.get({ id: terry.id })
+console.log('Remaining authors:', remainingMembers.data)
+console.log('Remaining pivot records:', remainingPivots.data)
+console.log('Author remains:', terryStillExists.name)
+```
+
+The Good Omens connection to Terry is removed, including that pivot record's
+contribution metadata. Neil's connection and Terry's author record remain.
+The relationship method returns undefined and takes identifiers in
+`relationshipData`. A resource PATCH with `data: { authors: [...] }`
+replaces the membership set; use relationship POST/DELETE for incremental changes.
+
+## HTTP endpoints
+
+After running all the blocks, Good Omens has only Neil:
+
+```bash
+curl --globoff 'http://localhost:3000/api/books/1?include=authors'
+curl 'http://localhost:3000/api/books/1/relationships/authors'
+curl --globoff 'http://localhost:3000/api/books?filter[authorName]=Neil'
+curl --globoff 'http://localhost:3000/api/book_authors?filter[book]=1'
+```
+
+Generated HTTP endpoints use JSON:API documents, including for the pivot
+resource. Use IDs returned by your server when adapting this example to an
+existing database.

package/docs/GUIDE/09-pagination-and-sorting.md

@@ -0,0 +1,149 @@
+---
+title: "Pagination and sorting"
+chapter: 9
+chapter_label: "09"
+---
+
+# 09. Pagination and sorting
+
+Pagination applies to the collection queried. A publisher query pages publishers;
+a publisher's to-many `getRelated` call pages its related records. Including
+children does not make the parent's page options paginate those children.
+
+Insert these blocks into the [starting script](03-running-example.md)
+on a fresh database, before the server starts.
+
+## Define a stable ordering
+
+```javascript
+await api.addResource('countries', {
+  queryDefaultLimit: 2,
+  queryMaxLimit: 3,
+  defaultSort: ['name'],
+  schema: {
+    name: { type: 'string', required: true, search: true },
+    code: { type: 'string', required: true }
+  }
+})
+await api.resources.countries.createKnexTable()
+for (const [name, code] of [
+  ['France', 'FR'], ['Germany', 'DE'], ['Austria', 'AT'],
+  ['Italy', 'IT'], ['United Kingdom', 'GB']
+]) {
+  await api.resources.countries.post({ data: { name, code }, returning: 'none' })
+}
+```
+
+The resource default sorts by name. A query may override it using
+`queryParams.sort`, for example `['-name']` for descending order. An ID tie-breaker
+provides stable ordering where the selected values are equal. `defaultSort`
+accepts a string or an array of strings; object-shaped defaults are rejected.
+
+## Default limits and numbered pages
+
+```javascript
+const defaultPage = await api.resources.countries.query({})
+const numbered = await api.resources.countries.query({
+  queryParams: { page: { number: 2, size: 2 } }
+})
+const emptyPage = await api.resources.countries.query({
+  queryParams: { page: { number: 10, size: 2 } }
+})
+console.log('Default records:', defaultPage.data)
+console.log('Second page:', numbered.data)
+console.log('Numbered metadata:', numbered.meta.pagination)
+console.log('Beyond the last page:', emptyPage.data)
+```
+
+Omitted page options, or `page: {}`, use the capped default limit and omit
+pagination metadata. Here, the default result is Austria and France.
+`page: { number: 2, size: 2 }` selects Germany and Italy. With pagination counts
+enabled, metadata is:
+
+```json
+{ "page": 2, "pageSize": 2, "pageCount": 3, "total": 5, "hasMore": true }
+```
+
+Page 10 returns an empty array. `enablePaginationCounts: false` suppresses the
+count query and count-derived metadata; do not assume every collection response
+contains totals. Every mode respects `queryMaxLimit`.
+
+## Cursor pages
+
+```javascript
+const firstCursorPage = await api.resources.countries.query({
+  queryParams: { sort: ['name'], page: { size: 2 } }
+})
+const nextCursor = firstCursorPage.meta.pagination.cursor.next
+const secondCursorPage = await api.resources.countries.query({
+  queryParams: { sort: ['name'], page: { size: 2, after: nextCursor } }
+})
+console.log('First cursor page:', firstCursorPage.data)
+console.log('Second cursor page:', secondCursorPage.data)
+```
+
+`page: { size: 2 }` starts cursor pagination. It returns Austria and France;
+the next page returns Germany and Italy. Cursor pages report `hasMore` and,
+when available, an opaque next cursor under `meta.pagination.cursor.next`.
+They do not count the collection. Treat cursors as opaque and keep the same sort,
+filters and fields when continuing. Returned links preserve those options.
+
+Use `after` or `before` with a returned cursor. Do not combine either boundary
+with `number`, supply both boundaries, or use an empty cursor string. Omitted
+page sizes use the resource default; explicitly keep the chosen size when
+constructing the next call yourself.
+
+## Sparse fields and ordering
+
+```javascript
+const sparse = await api.resources.countries.query({
+  queryParams: {
+    fields: { countries: 'code' },
+    sort: ['name'],
+    page: { size: 2 }
+  }
+})
+const nextSparse = await api.resources.countries.query({
+  queryParams: {
+    fields: { countries: 'code' },
+    sort: ['name'],
+    page: { size: 2, after: sparse.meta.pagination.cursor.next }
+  }
+})
+console.log('Sparse first page:', sparse.data)
+console.log('Sparse second page:', nextSparse.data)
+```
+
+The first sparse page contains IDs and codes AT/FR; the second contains DE/IT.
+The library retains the sort values needed internally without exposing omitted
+fields in the response. Sparse output is not permission to sort by hidden fields.
+
+Stored attributes, logical IDs and SQL query projections keep their own sort
+meaning when a search filter with the same name points elsewhere. A distinct
+sortable search alias can target a scalar stored field. Cursor values and
+relationship include `orderBy` follow the same field-resolution rules.
+
+## Derived and structured values
+
+Use [query projections](15-query-projections.md) when a derived SQL value
+must participate in sorting and cursors. JavaScript computed fields run after
+fetching and are not a replacement for SQL ordering.
+
+Object and array fields do not define a generic whole-document order. They are
+excluded from default sortable fields; explicitly making them sortable or using
+them in a default sort rejects schema compilation. Project a scalar JSON value
+when that is the intended ordering, and verify the SQL on your chosen backend.
+Stored SQL values drive cursor comparison; getters format returned values.
+
+## HTTP examples
+
+```bash
+curl --globoff 'http://localhost:3000/api/countries?page[number]=2&page[size]=2&sort=name'
+curl --globoff 'http://localhost:3000/api/countries?page[size]=2&sort=name'
+curl --globoff 'http://localhost:3000/api/countries?page[size]=2&sort=name&fields[countries]=code'
+```
+
+HTTP responses are JSON:API documents. Follow their returned links to continue
+pagination, preserving filters, fields, sort and size. See the
+[migration contract](33-migrating-to-v2.md#pagination-modes-and-counts) for removed
+options and count behavior.

package/docs/GUIDE/10-put-and-patch.md

@@ -0,0 +1,174 @@
+---
+title: "PUT and PATCH"
+chapter: 10
+chapter_label: "10"
+---
+
+# 10. PUT and PATCH
+
+PATCH changes supplied values. PUT describes a replacement and requires explicit
+values for persisted attributes and belongs-to relationships that already have
+values. PUT does not silently clear those stored values by omission.
+
+Relationship collections have an additional PUT rule: supplying a JSON:API
+`data.relationships` object makes omitted declared collections part of the
+replacement. An empty object can therefore clear collections. PATCH changes
+only the relationships named in its input.
+
+The following six blocks form one runnable example. Insert them in order into
+the [starting script](03-running-example.md) before starting its server,
+on a fresh database. JSON:API input makes the relationship-object boundary
+explicit; plain input is described below.
+
+## Create the example records
+
+```javascript
+await api.addResource('publishers', {
+  schema: { name: { type: 'string', required: true } },
+  relationships: { books: { type: 'hasMany', target: 'books', foreignKey: 'publisher_id' } }
+})
+await api.addResource('books', {
+  schema: {
+    title: { type: 'string', required: true },
+    note: { type: 'string', nullable: true },
+    publisher_id: { type: 'id', belongsTo: 'publishers', as: 'publisher', nullable: true }
+  }
+})
+await api.resources.publishers.createKnexTable()
+await api.resources.books.createKnexTable()
+const publisher = await api.resources.publishers.post({ data: { name: 'Example Press' } })
+const book = await api.resources.books.post({
+  data: { title: 'First edition', note: 'Keep me', publisher: publisher.id }
+})
+```
+
+The plain create calls still put data inside `data`, and refer to the
+relationship by its public name `publisher`, not its backing column.
+
+## PATCH retains omitted values
+
+```javascript
+const patched = await api.resources.books.patch({
+  id: book.id, format: 'jsonapi',
+  document: { data: { type: 'books', id: book.id, attributes: { title: 'Second edition' } } }
+})
+console.log(patched.data.attributes, patched.data.relationships.publisher.data)
+```
+
+The title changes. The note remains `Keep me` and the publisher linkage remains.
+A supplied to-many array replaces that relationship's membership; it is not an
+append operation. Use [relationship endpoints](11-relationship-endpoints.md)
+for explicit attachment/removal.
+
+## PUT requires explicit existing values
+
+```javascript
+let incompletePutError
+try {
+  await api.resources.books.put({
+    id: book.id, format: 'jsonapi',
+    document: { data: { type: 'books', id: book.id, attributes: { title: 'Rejected edition' } } }
+  })
+} catch (error) {
+  incompletePutError = error
+}
+const afterRejectedPut = await api.resources.books.get({ id: book.id })
+console.log(incompletePutError?.cause?.message, afterRejectedPut.title)
+```
+
+The owned write rejects with `RestApiWriteError`; its cause is a
+`RestApiValidationError` describing the omitted note and publisher. Its
+`transactionOutcome` is `rolledBack`, and the title remains `Second edition`.
+In an application, handle or propagate the error; the catch here lets the
+remaining examples run.
+
+```javascript
+const replaced = await api.resources.books.put({
+  id: book.id, format: 'jsonapi',
+  document: {
+    data: {
+      type: 'books', id: book.id,
+      attributes: { title: 'Third edition', note: null },
+      relationships: { publisher: { data: { type: 'publishers', id: publisher.id } } }
+    }
+  }
+})
+console.log(replaced.data.attributes, replaced.data.relationships.publisher.data)
+```
+
+This replacement explicitly clears the nullable note and retains the publisher.
+To clear the publisher, supply `publisher: { data: null }` in JSON:API
+relationships (or `publisher: null` in plain input). Required/non-nullable
+relationships cannot be detached this way. Computed and virtual fields are not
+persisted replacement values; ordinary required-field validation still applies.
+
+## PUT's relationship-object boundary
+
+```javascript
+await api.resources.publishers.put({
+  id: publisher.id, format: 'jsonapi',
+  document: { data: { type: 'publishers', id: publisher.id, attributes: { name: 'Renamed Press' } } }
+})
+const retainedBooks = await api.resources.publishers.getRelationship({ id: publisher.id, relationshipName: 'books' })
+await api.resources.publishers.put({
+  id: publisher.id, format: 'jsonapi',
+  document: {
+    data: {
+      type: 'publishers', id: publisher.id, attributes: { name: 'Empty Press' },
+      relationships: {}
+    }
+  }
+})
+const clearedBooks = await api.resources.publishers.getRelationship({ id: publisher.id, relationshipName: 'books' })
+const detachedBook = await api.resources.books.get({ id: book.id })
+console.log(retainedBooks.data, clearedBooks.data, detachedBook)
+```
+
+The first PUT has no relationships object and keeps the book membership. The
+second includes an empty object and detaches the book. The book record still
+exists; its nullable publisher is cleared. Plain read output omits an unassigned
+to-one relationship. A JSON:API linkage read represents it as `data: null`.
+
+The same omission boundary applies to declared many-to-many collections and
+reverse has-one relationships: replacing membership does not delete target
+records. Reverse changes can invoke child PATCH lifecycles and fail when the
+child cannot be detached. Ordinary through-row metadata and canonical links
+have different storage behavior; see [many-to-many relationships](08-many-to-many.md).
+
+## PATCH selects the relationship to replace
+
+```javascript
+await api.resources.publishers.patch({
+  id: publisher.id, format: 'jsonapi',
+  document: {
+    data: {
+      type: 'publishers', id: publisher.id,
+      relationships: { books: { data: [{ type: 'books', id: book.id }] } }
+    }
+  }
+})
+const reattachedBooks = await api.resources.publishers.getRelationship({ id: publisher.id, relationshipName: 'books' })
+const unchangedPublisher = await api.resources.publishers.get({ id: publisher.id })
+console.log(reattachedBooks.data, unchangedPublisher.name)
+```
+
+The book is attached again, and the publisher name remains `Empty Press`.
+For either method, an explicitly supplied empty collection clears membership.
+Omitted PATCH attributes and relationships remain unchanged.
+
+## Plain input and choosing the method
+
+Plain calls use `data: { title, note, publisher, ... }`. Supplying public
+relationship names causes their conversion into JSON:API relationship entries.
+A PUT that supplies one relationship can therefore clear other omitted
+collections. Use PATCH for a partial update, or explicitly include every
+relationship you intend to retain in a PUT replacement. Hooks that introduce a
+relationships object also participate in this boundary.
+
+Use `returning: 'full'`, `'minimal'` or `'none'` to select the write response;
+none/minimal do not skip write validation or mutation. See
+[hooks](13-hooks-and-lifecycle.md) for nested response reads and
+[managed transactions](19-managed-transactions.md) for atomic multi-call changes.
+Unconditional PUT can create a missing resource at the supplied ID; an
+`expectedVersion` condition cannot match a missing row. See
+[version-field migration](22-version-field-migrations.md) for conditional writes.

package/docs/GUIDE/11-relationship-endpoints.md

@@ -0,0 +1,174 @@
+---
+title: "Relationship endpoints"
+chapter: 11
+chapter_label: "11"
+---
+
+# 11. Relationship endpoints
+
+Relationship methods are part of `RestApiPlugin`; no extra relationship plugin
+is required. Install a storage plugin and an HTTP connector before registering
+resources. Configure the connector's `mountPath`, for example `/api`, as in the
+[quickstart](../QUICKSTART.md).
+
+There are two kinds of read endpoint:
+
+| Endpoint | Programmatic method | Response |
+| --- | --- | --- |
+| `/api/publishers/1/relationships/authors` | `getRelationship` | JSON:API identifier linkage |
+| `/api/publishers/1/authors` | `getRelated` | Related resource records |
+
+A linkage read returns a document even when programmatic record format is plain.
+A related read respects `format`: plain to-one reads return a record or null,
+plain to-many reads return a collection with `data`, and JSON:API reads return
+a document. Related reads apply the target's fields, filtering and pagination;
+they do not promise every related record in a single response.
+
+## Set up a runnable example
+
+Insert these blocks into the [starting script](03-running-example.md)
+on a fresh database, before the HTTP server starts.
+
+```javascript
+await api.addResource('publishers', {
+  schema: { name: { type: 'string', required: true } },
+  relationships: { authors: { type: 'hasMany', target: 'authors', foreignKey: 'publisher_id' } }
+})
+await api.addResource('authors', {
+  schema: {
+    name: { type: 'string', required: true },
+    publisher_id: { type: 'id', belongsTo: 'publishers', as: 'publisher', nullable: true }
+  }
+})
+await api.resources.publishers.createKnexTable()
+await api.resources.authors.createKnexTable()
+const publisher = await api.resources.publishers.post({ data: { name: 'Scribner' } })
+const stephen = await api.resources.authors.post({ data: { name: 'Stephen King' } })
+const peter = await api.resources.authors.post({ data: { name: 'Peter Straub' } })
+```
+
+The inverse relationships are explicitly declared. A `belongsTo` field does not
+automatically create an arbitrary reverse `hasOne` or `hasMany` endpoint.
+
+## Add membership and read each representation
+
+```javascript
+await api.resources.publishers.postRelationship({
+  id: publisher.id,
+  relationshipName: 'authors',
+  relationshipData: [
+    { type: 'authors', id: stephen.id },
+    { type: 'authors', id: peter.id }
+  ]
+})
+const linkage = await api.resources.publishers.getRelationship({
+  id: publisher.id, relationshipName: 'authors'
+})
+const related = await api.resources.publishers.getRelated({
+  id: publisher.id,
+  relationshipName: 'authors',
+  queryParams: { fields: { authors: 'name' }, sort: ['name'] }
+})
+console.log('Identifiers:', linkage.data)
+console.log('Records:', related.data)
+```
+
+Linkage contains `{ type: 'authors', id }` identifiers. Related records contain
+IDs and names, ordered Peter then Stephen. Relationship-only writes take
+`relationshipData`, not `data`; HTTP wraps that linkage in a `data` member.
+POST adds members and DELETE removes specified members; both apply only to
+supported to-many relationships. PATCH replaces a to-many set or a to-one target.
+All three relationship write methods return undefined.
+
+## Replace and remove members
+
+```javascript
+await api.resources.publishers.patchRelationship({
+  id: publisher.id,
+  relationshipName: 'authors',
+  relationshipData: [{ type: 'authors', id: stephen.id }]
+})
+const replaced = await api.resources.publishers.getRelationship({
+  id: publisher.id, relationshipName: 'authors'
+})
+await api.resources.publishers.deleteRelationship({
+  id: publisher.id,
+  relationshipName: 'authors',
+  relationshipData: [{ type: 'authors', id: stephen.id }]
+})
+const empty = await api.resources.publishers.getRelationship({
+  id: publisher.id, relationshipName: 'authors'
+})
+console.log('After replacement:', replaced.data)
+console.log('After removal:', empty.data)
+```
+
+Replacement leaves Stephen alone; removal leaves an empty array. Authors remain
+in the database. With `hasMany`, detachment clears the child's nullable foreign
+key. With ordinary many-to-many storage, it removes the pivot row. Required
+relationships cannot be cleared by detaching a child.
+
+## Change and clear a to-one target
+
+```javascript
+await api.resources.authors.patchRelationship({
+  id: peter.id,
+  relationshipName: 'publisher',
+  relationshipData: { type: 'publishers', id: publisher.id }
+})
+const peterPublisher = await api.resources.authors.getRelated({
+  id: peter.id, relationshipName: 'publisher'
+})
+await api.resources.authors.patchRelationship({
+  id: peter.id, relationshipName: 'publisher', relationshipData: null
+})
+const cleared = await api.resources.authors.getRelationship({
+  id: peter.id, relationshipName: 'publisher'
+})
+console.log('Related publisher:', peterPublisher.name)
+console.log('Cleared linkage:', cleared.data)
+```
+
+The related read returns Scribner; the final linkage is null. Use null only when
+the relationship permits it. Polymorphic linkage also requires its target type;
+see [polymorphic relationships](07-polymorphic-relationships.md).
+
+## HTTP equivalents
+
+After running all blocks, both authors are unassigned. These commands add them,
+read both endpoints, and clear the collection again:
+
+```bash
+curl -X POST http://localhost:3000/api/publishers/1/relationships/authors \
+  -H 'Content-Type: application/vnd.api+json' \
+  -d '{"data":[{"type":"authors","id":"1"},{"type":"authors","id":"2"}]}'
+curl http://localhost:3000/api/publishers/1/relationships/authors
+curl --globoff 'http://localhost:3000/api/publishers/1/authors?fields[authors]=name&sort=name'
+curl -X PATCH http://localhost:3000/api/publishers/1/relationships/authors \
+  -H 'Content-Type: application/vnd.api+json' \
+  -d '{"data":[]}'
+```
+
+Successful generated relationship writes return HTTP 204 without a body. Use IDs
+returned by the server for persistent databases. Resource PATCH is a different
+body shape: `data.type`, `data.id`, and `data.relationships` alongside any
+attributes being changed.
+
+## Permissions and transactions
+
+Relationship operations apply their method-specific permission checks and
+resource/target visibility. Linkage discovery is not a bypass for related query
+permissions. Ordinary pivot rows also have their own query visibility; canonical
+links are separate from pivot resource rows. Configure hooks through
+`api.customize` using the [hook guide](13-hooks-and-lifecycle.md).
+
+A successful relationship write participates in the library's transaction
+lifecycle. Compose several operations with a handle from
+[`api.transaction`](19-managed-transactions.md). A loop of independent operations
+is not a single atomic transaction. Failures report the
+[write outcome](20-transaction-outcomes.md); do not blindly retry an unknown outcome.
+
+Use relationship writes for membership-only changes, related reads for records,
+and resource PATCH when updating attributes and relationships together. Where
+provided, follow response links for discovery and pagination; relative links
+must be resolved against the API URL by clients that require absolute URLs.