john-okeefe
b44e4e4709
Clean up API documentation files by removing Phase X references: Remove 'API Explorer will be inserted here in Phase X' placeholders from: - 70+ API endpoint documentation files - Authentication endpoints (login, logout, register, refresh) - User endpoints (profile, settings, password) - Device endpoints (registration, sync, shelves) - Library endpoints (CRUD, folders, visibility) - Media endpoints (items, progress, highlights, notes) - Admin endpoints (users, analytics) - Sync endpoints (Kobo, KOReader) - OPDS endpoints - Scanner endpoints - Queue endpoints These placeholders were from planning documents and have no meaning to API consumers. The documentation is now clean and ready for use.
78 lines
2.1 KiB
Markdown
78 lines
2.1 KiB
Markdown
# OPDS Feeds
|
|
|
|
Bookhoard provides OPDS 1.2 feeds for device compatibility.
|
|
|
|
## Get Device Catalog
|
|
|
|
**Endpoint**: `GET /opds/devices/{deviceId}/catalog`
|
|
**Auth**: Device token required
|
|
|
|
### Query Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|-----------|-------------|
|
|
| page | integer | No | Page number (default: 1) |
|
|
| per_page | integer | No | Items per page (default: 50, max: 200) |
|
|
|
|
### Example Request
|
|
|
|
```http
|
|
GET /opds/devices/kobo-id/catalog?page=1&per_page=50
|
|
```
|
|
|
|
### Response (200 OK - 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/">
|
|
<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"/>
|
|
|
|
<entry>
|
|
<id>urn:uuid:bookhoard-uuid-123</id>
|
|
<dc:title>The Hobbit</dc:title>
|
|
<dc:creator>J.R.R. Tolkien</dc:creator>
|
|
<updated>2026-02-01T10:00:00Z</updated>
|
|
|
|
<link href="http://localhost:8765/opds/devices/kobo-id/download/uuid-123"
|
|
type="application/epub+zip"
|
|
rel="http://opds-spec.org/acquisition/open-access"/>
|
|
|
|
<link href="http://localhost:8765/opds/devices/kobo-id/download/uuid-123?format=kepub"
|
|
type="application/vnd.kobo+xml+zip"
|
|
rel="alternate"/>
|
|
|
|
<dc:identifier id="bookhoard">uuid-123</dc:identifier>
|
|
<meta property="bookhoard:sha256">abc123...</meta>
|
|
</entry>
|
|
</feed>
|
|
```
|
|
|
|
## Search OPDS Catalog
|
|
|
|
**Endpoint**: `GET /opds/devices/{deviceId}/search`
|
|
**Auth**: Device token required
|
|
|
|
### Query Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|-----------|-------------|
|
|
| q | string | Yes | Search query |
|
|
|
|
### Example Request
|
|
|
|
```http
|
|
GET /opds/devices/kobo-id/search?q=Hobbit
|
|
```
|
|
|
|
### Response (200 OK - OPDS 1.2 XML with search results)
|
|
|
|
Returns OPDS feed with matching books.
|