131 lines
3.3 KiB
Markdown
131 lines
3.3 KiB
Markdown
# Supafolio & TypeSense API Documentation
|
|
|
|
Complete API documentation for book metadata search services, extracted from the [Supapress WordPress plugin](https://wordpress.org/plugins/supapress/).
|
|
|
|
## Overview
|
|
|
|
This repository contains comprehensive documentation for two book metadata APIs:
|
|
|
|
| API | Type | Use Case |
|
|
|-----|------|----------|
|
|
| **Supafolio** | Managed service | Quick setup, ONIX support, minimal technical overhead |
|
|
| **TypeSense** | Self-hosted | Large datasets, custom ranking, data privacy, full control |
|
|
|
|
Documentation was extracted because the vendor (Supadu) did not provide adequate API documentation.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- API credentials for your chosen service
|
|
- `curl` or any HTTP client
|
|
- (TypeSense only) A running TypeSense instance
|
|
|
|
### Configuration
|
|
|
|
1. Copy the template and add your credentials:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. Edit `.env` with your actual API keys:
|
|
```env
|
|
SUPAFOLIO_API_KEY=your_supafolio_key_here
|
|
TYPESENSE_API_KEY=your_typesense_key_here
|
|
```
|
|
|
|
3. Source the environment file before running commands:
|
|
```bash
|
|
source .env
|
|
```
|
|
|
|
### Test Supafolio API
|
|
|
|
```bash
|
|
source .env
|
|
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
|
|
"https://api.supafolio.com/v2/search?keyword=javascript&amount=10"
|
|
```
|
|
|
|
### Test TypeSense API
|
|
|
|
```bash
|
|
source .env
|
|
curl -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
|
|
"https://your-typesense-host/collections/books/documents/search?q=javascript&query_by=title,description"
|
|
```
|
|
|
|
## Documentation Files
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| [supafolio-api-complete.md](supafolio-api-complete.md) | Full Supafolio API reference with endpoints, parameters, and response schemas |
|
|
| [typesense-api-complete.md](typesense-api-complete.md) | Full TypeSense API reference for self-hosted search |
|
|
| [api-comparison-guide.md](api-comparison-guide.md) | Side-by-side comparison with decision matrix and cost analysis |
|
|
| [supapress-api-analysis.md](supapress-api-analysis.md) | Original analysis of Supapress plugin integration |
|
|
|
|
## Choosing an API
|
|
|
|
### Use Supafolio When:
|
|
|
|
- Small to medium catalog (< 50,000 books)
|
|
- Limited technical resources
|
|
- Need ONIX data integration
|
|
- Quick setup required
|
|
- Managed service preferred
|
|
|
|
### Use TypeSense When:
|
|
|
|
- Large catalog (> 50,000 books)
|
|
- High search volume
|
|
- Custom ranking/faceting needed
|
|
- Data privacy/compliance required
|
|
- Technical team available for maintenance
|
|
|
|
See [api-comparison-guide.md](api-comparison-guide.md) for detailed comparison and scoring matrix.
|
|
|
|
## Common Operations
|
|
|
|
### Book Search
|
|
|
|
```bash
|
|
source .env
|
|
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
|
|
"https://api.supafolio.com/v2/search?keyword=programming&amount=20"
|
|
```
|
|
|
|
### ISBN Lookup
|
|
|
|
```bash
|
|
source .env
|
|
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
|
|
"https://api.supafolio.com/v2/search?isbns=9781234567890,9780987654321"
|
|
```
|
|
|
|
### Predictive Search
|
|
|
|
```bash
|
|
source .env
|
|
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
|
|
"https://api.supafolio.com/v2/predictive?keyword=javascrip&amount=5"
|
|
```
|
|
|
|
### Get Filter Values
|
|
|
|
```bash
|
|
source .env
|
|
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
|
|
"https://api.supafolio.com/v2/searchfilter?filters=format,collection,publisher"
|
|
```
|
|
|
|
## Source
|
|
|
|
- Extracted from: wordpress.org/plugins/supapress/
|
|
- Generated: 2026-01-24
|
|
- Supafolio API Version: v2.26.2
|
|
- TypeSense API Version: v29.0
|
|
|
|
## License
|
|
|
|
See [LICENSE](LICENSE) file for details.
|