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

18 KiB
Raw Blame History

Supafolio API Complete Documentation

Overview

Supafolio is a proprietary book metadata management service developed by Supadu specifically for the publishing industry. It specializes in ingesting ONIX (Online Information Exchange) data and transforming it into web-friendly content for publisher websites, stores, and marketing pages.

Key Features

  • ONIX Integration: Native support for ONIX 2.1 & 3.0 data formats
  • Publishing Industry Focus: Specialized features for books, authors, and publishers
  • Managed Service: No infrastructure maintenance required
  • Real-time Updates: Automatic daily data refresh by default
  • Metadata Enrichment: Add supplementary data beyond ONIX standards
  • Dynamic Collections: Create custom collections on-the-fly
  • SEO Optimization: Built-in SEO features for book discovery
  • Multi-currency Support: Price display in multiple currencies

Authentication

Method: Header-Based Authentication

curl -H "x-apikey: {api_key}" \
  "https://api.supafolio.com/v2/{endpoint}"

Configuration in Supapress Plugin

function supapress_call_supafolio($service, $params, $properties = array(), $cacheCalls = true) {
    // Base URL configuration
    if ((string)get_option('service_url') !== '') {
        $baseUrl = rtrim(get_option('service_url'), '/') . '/';
    } else {
        $baseUrl = SUPAPRESS_DEFAULT_SERVICE_URL;
    }
    
    // API key configuration
    if ((string)get_option('api_key') !== '') {
        $api = trim(get_option('api_key'));
    } else {
        $api = SUPAPRESS_DEFAULT_SERVICE_API;
        $baseUrl .= 'v2/';
    }
    
    // HTTP request via WordPress HTTP API
    $response = wp_remote_post($url, array(
        'method'      => 'GET',
        'timeout'     => 45,
        'redirection' => 5,
        'httpversion' => '1.0',
        'blocking'    => true,
        'headers'     => array('x-apikey' => $api),
        'body'        => array(),
        'cookies'     => array()
    ));
}

Required Settings

  • api_key: Supafolio API authentication key
  • service_url: Custom API endpoint URL (optional)
  • Default API Key: 9819864f6ff0e8a5a097c99224cfd18a
  • Default URL: https://api.supafolio.com/v2/

Complete API Endpoints Reference

1. Search Endpoint

Endpoint: GET /v2/search

Purpose: Primary search operation for finding books based on various criteria.

Complete Parameter Reference

Parameter Required Description Example
keyword no Search term for text matching "javascript programming"
isbns no Comma-separated ISBN list "9781234567890,9780987654321"
collection no Collection name filter "fiction"
amount no Results count (default: 10) 100
page no Page number (default: 1) 2
order no Sort order (default: relevance) publishdate-desc
format no Format filter "hardback"
publisher no Publisher name filter "Penguin Random House"
imprint no Imprint name filter "Penguin Classics"
series no Series name filter "Harry Potter"
category no Category name filter "Science Fiction"
from_date no Publication date range start "2024-01-01"
to_date no Publication date range end "2024-12-31"
from no Alternative date range start "2024-01-01"
to no Alternative date range end "2024-12-31"
award_winner no Award winner filter "true"
starts_with no Title prefix filter "Java"
exclude_imprint no Exclude specific imprint "Classic Books"
exclude_category no Exclude specific category "Academic"
distinct no Return distinct results "true"
primary_format no Primary format filter "paperback"
guides no Guide filter "teacher"
age no Age range filter "adult"
contributor no Contributor filter "John Smith"
title no Title filter "JavaScript"
type no Product type filter "book"

Advanced Parameters (from shortcode attributes)

Parameter Description Example
include_price Include additional format prices "true"
include_promo_price Include promotional prices "true"
search_type Search type specification "author"
ignore_primary_format Return all format rules "true"
series_data Include series information "true"
imprint_data Include imprint information "true"
publisher_data Include publisher information "true"
category_data Include category information "true"
locale Set locale "en_US"
role Filter by author role "author"
get_parent_tree Get category parent tree "true"

Sort Order Options

Option Description Example
relevance Default relevance ranking Default
publishdate-desc Newest to oldest publicationDate:desc
publishdate-asc Oldest to newest publicationDate:asc
title-az Title A to Z title:asc
title-za Title Z to A title:desc
price-asc Price low to high price:asc
price-desc Price high to low price:desc
contributor-az Contributor A to Z contributor:asc
contributor-za Contributor Z to A contributor:desc

Sample Request

curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/search?keyword=javascript&isbns=9781234567890,9780987654321&amount=20&order=publishdate-desc"

Sample Response

{
  "status": "success",
  "data": {
    "search": [
      {
        "isbn13": "9781234567890",
        "isbn10": "1234567890",
        "title": "JavaScript: The Good Parts",
        "authors": [
          {
            "name": "Douglas Crockford"
          }
        ],
        "publicationDate": {
          "date": "2014-05-15 00:00:00",
          "timezone": "UTC"
        },
        "saleDate": {
          "date": "2014-06-01 00:00:00", 
          "timezone": "UTC"
        },
        "prices": [
          {
            "locale": "USD",
            "amount": 29.99,
            "discount": 0.00
          },
          {
            "locale": "GBP",
            "amount": 19.99,
            "discount": 10.00
          }
        ],
        "image": "https://example.com/covers/js-good-parts.jpg",
        "formats": [
          {
            "format": {
              "name": "Hardcover",
              "format_id": 1
            },
            "isbn": "9781234567890"
          }
        ],
        "publisher": {
          "name": "O'Reilly Media",
          "id": 123
        },
        "imprint": {
          "name": "O'Reilly Professional",
          "id": 456
        },
        "series": [
          {
            "series": {
              "name": "JavaScript Series",
              "id": 789
            }
          }
        ],
        "categories": [
          {
            "category": {
              "name": "Programming",
              "id": 456,
              "parent_id": 123
            }
          }
        ]
      }
    ],
    "pagination": {
      "results": {
        "amount": 1,
        "total": 1
      },
      "pages": {
        "current": 1,
        "total": 1
      }
    }
  }
}

2. Predictive Search Endpoint

Endpoint: GET /v2/predictive

Purpose: Autocomplete/search suggestions for user input.

Parameters

Parameter Required Description Default
keyword yes Search term for suggestions "javascript"
amount no Number of suggestions 10
type no Product type "Products"

Sample Request

curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/predictive?keyword=javascript&amount=10&type=Products"

Sample Response

{
  "status": "success",
  "data": {
    "predictive": [
      {
        "isbn13": "9781234567890",
        "title": "JavaScript: The Definitive Guide",
        "image": "https://example.com/covers/js-definitive-guide.jpg"
      }
    ]
  }
}

3. Search Filter Endpoint

Endpoint: GET /v2/searchfilter

Purpose: Retrieve available filter values for dynamic navigation.

Parameters

Parameter Required Description Example
filters yes Filter type "format"

Sample Requests

# Get format filters
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/searchfilter?filters=format"

# Get collection filters
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/searchfilter?filters=collection"

# Get multiple filter types
curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/searchfilter?filters=format,collection,publisher"

Sample Response

{
  "status": "success",
  "data": {
    "filters": {
      "format": {
        "values": [
          {
            "name": "Hardcover",
            "seo_name": "hardcover",
            "count": 1234
          },
          {
            "name": "Paperback", 
            "seo_name": "paperback",
            "count": 987
          },
          {
            "name": "Ebook",
            "seo_name": "ebook",
            "count": 456
          }
        ]
      }
    }
  }
}

4. Book Details Endpoint

Endpoint: GET /v2/book/{isbn}

Purpose: Retrieve comprehensive information for a specific book.

Parameters

All search parameters are supported for book details, including:

  • include_price, include_promo_price
  • series_data, imprint_data, publisher_data, category_data
  • locale, role, get_parent_tree

Sample Request

curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/book/9781234567890?include_price=true&series_data=true"

5. Bulk Operations

The search endpoint supports bulk operations through:

  • Multiple ISBN specification in isbns parameter
  • High amount values (up to several hundred)

Bulk ISBN Lookup

curl -H "x-apikey: xyz" \
  "https://api.supafolio.com/v2/search?isbns=9781234567890,9780987654321,9781111111111,9782222222222&amount=200"

Complete Data Schema

Book Object Structure

{
  "book": {
    "isbn13": "string (13-digit ISBN)",
    "isbn10": "string (10-digit ISBN)", 
    "title": "string (full title)",
    "subtitle": "string (subtitle/edition)",
    "description": "string (full description)",
    "summary": "string (brief summary)",
    "seo": "string (SEO-optimized title)",
    "date": {
      "date": "YYYY-MM-DD HH:MM:SS",
      "timezone": "string (UTC by default)"
    },
    "saleDate": {
      "date": "YYYY-MM-DD HH:MM:SS", 
      "timezone": "string"
    },
    "prices": [
      {
        "locale": "USD|GBP|CAD|AUD|NZD|EUR|JPY",
        "amount": "number (decimal)",
        "discount": "number (decimal)"
      }
    ],
    "image": "url (cover image URL)",
    "formats": [
      {
        "format": {
          "name": "string",
          "format_id": "number"
        },
        "isbn": {
          "isbn": "string" | "string"
        }
      }
    ],
    "contributors": [
      {
        "contributor": {
          "name": "string",
          "bio": "string (author biography)",
          "seo": "string (SEO-friendly name)"
        }
      }
    ],
    "publisher": {
      "name": "string",
      "id": "number"
    },
    "imprint": {
      "name": "string",
      "id": "number"
    },
    "series": [
      {
        "series": {
          "name": "string",
          "id": "number"
        }
      }
    ],
    "categories": [
      {
        "category": {
          "name": "string",
          "id": "number",
          "parent_id": "number"
        }
      }
    ],
    "collections": [
      {
        "collection": {
          "name": "string", 
          "id": "number"
        }
      }
    ],
    "assets": [
      {
        "asset": {
          "type": "string",
          "sub_type": "string",
          "path": "string", 
          "width": "number",
          "height": "number"
        }
      }
    ],
    "trim": {
      "width": "number",
      "height": "number", 
      "depth": "number",
      "unit": "string"
    },
    "weight": {
      "weight": "number",
      "weight_unit": "string"
    },
    "pages": "number",
    "edition": "string",
    "awards": [
      {
        "award": {
          "name": "string",
          "id": "number"
        }
      }
    ],
    "reviews": [
      {
        "review": {
          "description": "string"
        }
      }
    ],
    "retailers": [
      {
        "label": "string",
        "path": "string", 
        "seo": "string"
      }
    ]
  },
  "pagination": {
    "results": {
      "amount": "number",
      "total": "number"
    },
    "pages": {
      "current": "number", 
      "total": "number"
    }
  },
  "filters": {
    "{filter_name}": {
      "values": [
        {
          "name": "string",
          "seo_name": "string", 
          "count": "number"
        }
      ]
    }
  }
}

Industry-Specific Features

ONIX Data Support

  • Format Versions: ONIX 2.1 & 3.0 support
  • Field Mapping: Automatic ONIX to web field conversion
  • Code Lists: Standard publishing industry codes
  • Validation: ONIX compliance checking

Publishing Workflow Integration

  • Title Management: Automatic title overrides
  • Collection Management: Dynamic collection creation
  • Business Rules: Custom pricing and availability rules
  • Territorial Rights: Region-specific content management
  • Metadata Enrichment: Add video, audio, supplementary content

Multi-Currency Support

"prices": [
  {
    "locale": "USD",
    "amount": 29.99,
    "discount": 5.00
  },
  {
    "locale": "GBP", 
    "amount": 24.99,
    "discount": 10.00
  },
  {
    "locale": "EUR",
    "amount": 27.99,
    "discount": 0.00
  }
]

Retailer Integration

"retailers": [
  {
    "label": "Amazon",
    "path": "https://amazon.com/dp/{isbn}",
    "seo": "amazon-com"
  },
  {
    "label": "Barnes & Noble",
    "path": "https://bn.com/dp/{isbn}",
    "seo": "barnes-noble-com"
  }
]

Advanced Features

Caching System

WordPress Integration

// Cache key generation
$cacheKey = supapress_get_cache_prefix() . md5($url . $api);

// Object caching
if (supapress_is_object_caching()) {
    return get_site_transient($cacheKey, $data, $lifetime);
}

// File-based caching
if (supapress_is_file_caching()) {
    $path = supapress_cache_get_file_path($cacheKey);
    return file_put_contents($path, gzdeflate(json_encode($data)));
}

Cache Configuration

Setting Description Default
Object Caching Uses WordPress object cache Enabled if available
File Caching Compressed JSON files Fallback if no object cache
Default Lifetime 24 hours (DAY_IN_SECONDS) Configurable per widget type
Cache Prefix spcache- Rotating for cache invalidation

Error Handling

Standard Response Format

{
  "status": "error",
  "data": {
    "errors": [
      {
        "message": "Error description"
      }
    ]
  }
}

Common Error Messages

  • "Product not in database" - ISBN not found
  • "Something went wrong: {error}" - Generic error with details
  • "No books found" - Empty search results

SEO Integration

Yoast SEO Overrides

// Title override
add_filter('wpseo_title', function($title) use ($book) {
    return supapress_translate_template_text($text_template, $book);
});

// Description override  
add_filter('wpseo_metadesc', function($desc) use ($book) {
    return supapress_translate_template_text($desc_template, $book);
});

// Canonical URL override
add_filter('wpseo_canonical', function($url) use ($book) {
    return site_url() . supapress_translate_template_url($url_template, $book);
});

URL Template Variables

Variable Description Example
%isbn13% 13-digit ISBN 9781234567890
%isbn10% 10-digit ISBN 1234567890
%title% Book title javascript-the-good-parts
%subtitle% Book subtitle advanced-concepts
%author% Author name douglas-crockford
%publisher% Publisher name oreilly-media
%price_usd% USD price 29.99
%discount_usd% USD discount 5.00
%price_gbp% GBP price 24.99
%discount_gbp% GBP discount 10.00

Performance Characteristics

Request Limits

  • Timeout: 45 seconds per request
  • Redirection: 5 redirects maximum
  • HTTP Version: 1.0
  • Rate Limiting: Managed by Supafolio service

Optimization Strategies

  • Bulk Operations: Use ISBN lists for efficiency
  • Caching: Leverage built-in WordPress caching
  • Selective Fields: Use include_* parameters wisely
  • Pagination: Implement proper page navigation
  • Filter Early: Apply filters before full-text search

Security Features

Authentication Security

  • Header-based: API key sent in HTTP headers (not URL parameters)
  • HTTPS Required: All requests use secure protocol
  • Input Validation: WordPress sanitization functions applied

Data Privacy

  • Managed Service: Supafolio handles data privacy and compliance
  • Industry Standards: ONIX format compliance
  • GDPR Considerations: Built-in data protection features

Integration Examples

WordPress Shortcode

[supapress type="isbn_lookup" 
    isbns="9781234567890,9780987654321"
    amount="50"
    include_price="true"
    series_data="true"]

JavaScript Integration

// AJAX search request
fetch('/wp-admin/admin-ajax.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
        action: 'supapress_search',
        keyword: 'javascript',
        amount: 20,
        widget_id: '123'
    })
})
.then(response => response.json())
.then(data => {
    // Process search results
});

Generated: 2026-01-24
Supafolio Version: v2.26.2
Supapress Plugin: v2.26.2