704 lines
18 KiB
Markdown
704 lines
18 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
curl -H "x-apikey: {api_key}" \
|
|
"https://api.supafolio.com/v2/{endpoint}"
|
|
```
|
|
|
|
#### Configuration in Supapress Plugin
|
|
|
|
```php
|
|
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 | Default |
|
|
|------------|----------|-------------|---------|
|
|
| `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
|
|
```bash
|
|
curl -H "x-apikey: xyz" \
|
|
"https://api.supafolio.com/v2/search?keyword=javascript&isbns=9781234567890,9780987654321&amount=20&order=publishdate-desc"
|
|
```
|
|
|
|
#### Sample Response
|
|
```json
|
|
{
|
|
"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
|
|
```bash
|
|
curl -H "x-apikey: xyz" \
|
|
"https://api.supafolio.com/v2/predictive?keyword=javascript&amount=10&type=Products"
|
|
```
|
|
|
|
#### Sample Response
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
# 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
|
|
```json
|
|
{
|
|
"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
|
|
```bash
|
|
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
|
|
```bash
|
|
curl -H "x-apikey: xyz" \
|
|
"https://api.supafolio.com/v2/search?isbns=9781234567890,9780987654321,9781111111111,9782222222222&amount=200"
|
|
```
|
|
|
|
## Complete Data Schema
|
|
|
|
### Book Object Structure
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
"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
|
|
```json
|
|
"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
|
|
```php
|
|
// 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
|
|
```json
|
|
{
|
|
"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
|
|
```php
|
|
// 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
|
|
|
|
```php
|
|
[supapress type="isbn_lookup"
|
|
isbns="9781234567890,9780987654321"
|
|
amount="50"
|
|
include_price="true"
|
|
series_data="true"]
|
|
```
|
|
|
|
### JavaScript Integration
|
|
|
|
```javascript
|
|
// 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 |