From 1f5b0d01649f5e739377cf5200dba39ec0588c46 Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Thu, 30 Jul 2026 12:12:58 -0400
Subject: [PATCH] docs(api): document OPDS pagination links and OpenSearch
 search

Update the OPDS section of the API reference to reflect the now-working
catalog:

- Document the page/per_page parameters and that paging is driven by the
  rel=next/previous/first/last links plus OpenSearch paging metadata.
- Refresh the example feed XML to show the pagination links, opensearch
  namespace/elements, and standard Atom <title>/<author> elements.
- Document the search endpoint's two modes: OpenSearch description
  (application/opensearchdescription+xml, no q) and results feed (with q),
  with an example description document.
---
 docs/developer/api-reference.md | 48 +++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 8 deletions(-)

diff --git a/docs/developer/api-reference.md b/docs/developer/api-reference.md
index 046cd43..916bf11 100644
--- a/docs/developer/api-reference.md
+++ b/docs/developer/api-reference.md
@@ -986,25 +986,39 @@ GET /opds/devices/{deviceId}/catalog?page={page}&per_page={per_page}
 - `page` (optional): Page number (default: 1)
 - `per_page` (optional): Items per page (default: 50, max: 200)
 
+The feed is paginated via standard OPDS link relations. Clients (e.g. KOReader)
+walk pages by following the `rel="next"` link until it is absent. OpenSearch
+paging metadata (`totalResults`, `itemsPerPage`, `startIndex`) is also included.
+
 **Response** (200 - OPDS 1.2 XML):
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom"
        xmlns:opds="http://opds-spec.org/2010/"
-       xmlns:dc="http://purl.org/dc/elements/1.1/">
+       xmlns:dc="http://purl.org/dc/elements/1.1/"
+       xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
   <id>urn:uuid:device-id</id>
   <title>Bookhoard Library</title>
   <updated>2026-02-01T12:00:00Z</updated>
 
-  <link rel="self" href="http://localhost:8765/opds/devices/kobo-id/catalog"/>
-  <link rel="search" href="http://localhost:8765/opds/devices/kobo-id/search"/>
-  <link rel="start" href="http://localhost:8765/opds/devices/kobo-id/nav"/>
+  <link rel="self" href="http://localhost:8765/opds/devices/kobo-id/catalog?page=2&per_page=50"/>
+  <link rel="start" href="http://localhost:8765/opds/devices/kobo-id/catalog?page=1&per_page=50"/>
+  <link rel="first" href="http://localhost:8765/opds/devices/kobo-id/catalog?page=1&per_page=50"/>
+  <link rel="previous" href="http://localhost:8765/opds/devices/kobo-id/catalog?page=1&per_page=50"/>
+  <link rel="next" href="http://localhost:8765/opds/devices/kobo-id/catalog?page=3&per_page=50"/>
+  <link rel="last" href="http://localhost:8765/opds/devices/kobo-id/catalog?page=37&per_page=50"/>
+  <link rel="search" type="application/opensearchdescription+xml"
+        href="http://localhost:8765/opds/devices/kobo-id/search"/>
+
+  <opensearch:totalResults>1814</opensearch:totalResults>
+  <opensearch:itemsPerPage>50</opensearch:itemsPerPage>
+  <opensearch:startIndex>51</opensearch:startIndex>
 
   <entry>
     <id>urn:uuid:bookhoard-uuid-123</id>
-    <dc:title>The Hobbit</dc:title>
-    <dc:creator>J.R.R. Tolkien</dc:creator>
+    <title>The Hobbit</title>
+    <author><name>J.R.R. Tolkien</name></author>
     <updated>2026-02-01T10:00:00Z</updated>
 
     <link href="http://localhost:8765/opds/devices/kobo-id/download/uuid-123"
@@ -1043,10 +1057,28 @@ GET /opds/devices/{deviceId}/download/{bookId}?format={format}
 ### Search OPDS Catalog
 
 ```http
-GET /opds/devices/{deviceId}/search?q={query}
+GET /opds/devices/{deviceId}/search            # OpenSearch description
+GET /opds/devices/{deviceId}/search?q={query}  # search results feed
 ```
 
-**Response** (200 - OPDS 1.2 XML with search results)
+When called **without** a `q` parameter, returns an OpenSearch description
+document (`application/opensearchdescription+xml`). OPDS clients fetch this to
+learn the search URL template, then substitute `{searchTerms}`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
+  <ShortName>Bookhoard</ShortName>
+  <Description>Search the Bookhoard library</Description>
+  <InputEncoding>UTF-8</InputEncoding>
+  <OutputEncoding>UTF-8</OutputEncoding>
+  <Url type="application/atom+xml;profile=opds-catalog;kind=acquisition"
+       template="http://localhost:8765/opds/devices/kobo-id/search?q={searchTerms}"/>
+</OpenSearchDescription>
+```
+
+When called **with** a `q` parameter, **Response** (200 - OPDS 1.2 XML with
+search results, including `opensearch:totalResults`).
 
 ### List Available Formats