WVUPress/supafolio-api-docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
supafolio-api-docs/README.md

3.3 KiB
Raw Blame History

Supafolio & TypeSense API Documentation

Complete API documentation for book metadata search services, extracted from the Supapress WordPress plugin.

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:

    cp .env.example .env

  2. Edit .env with your actual API keys:

    SUPAFOLIO_API_KEY=your_supafolio_key_here
TYPESENSE_API_KEY=your_typesense_key_here

  3. Source the environment file before running commands:

    source .env

Test Supafolio API

source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/search?keyword=javascript&amount=10"

Test TypeSense API

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 Full Supafolio API reference with endpoints, parameters, and response schemas
typesense-api-complete.md Full TypeSense API reference for self-hosted search
api-comparison-guide.md Side-by-side comparison with decision matrix and cost analysis
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 for detailed comparison and scoring matrix.

Common Operations

Book Search

source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/search?keyword=programming&amount=20"

ISBN Lookup

source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/search?isbns=9781234567890,9780987654321"

Predictive Search

source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/predictive?keyword=javascrip&amount=5"

Get Filter Values

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 file for details.