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

9.7 KiB
Raw Blame History

Supapress Plugin API Analysis - Supafolio API Access Guide

Initial Request

User: There is a plugin in /var/www/html/wp-content/plugins/supapress which queries an API with credentials, our credential is $SUPAFOLIO_API_KEY , I want to know, based on the code how we can acces the API with curl?

Plugin Analysis Process

Directory Structure Discovery

I first examined the Supapress plugin directory structure to understand the codebase:

/var/www/html/wp-content/plugins/supapress/
├── includes/
│   ├── functions.php
│   ├── typesense-functions.php
│   ├── widget.php
│   ├── controller.php
│   └── book.php
├── admin/
│   ├── admin.php
│   └── functions.php
├── views/
├── supapress.php (main plugin file)
└── settings.php

Code Analysis Approach

I searched for API-related patterns and credential usage in the plugin files:

  1. Credential Search: Looked for the specific credential $SUPAFOLIO_API_KEY
  2. API Pattern Analysis: Searched for curl, wp_remote_get, wp_remote_post, api_key, credential, token
  3. Function Analysis: Examined the main API calling functions

Key Findings

Two API Systems Discovered

  1. Supafolio API (default system)
  2. TypeSense API (alternative system)

Main Plugin Configuration

From supapress.php:

define('SUPAPRESS_DEFAULT_SERVICE_URL', 'https://api.supafolio.com/v2/');
define('SUPAPRESS_DEFAULT_SERVICE_API', '9819864f6ff0e8a5a097c99224cfd18a');

Detailed API Analysis

Supafolio API Structure

Core Function: supapress_call_supafolio()

Located in includes/functions.php:56-171:

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/';
    }
    
    // URL construction
    $url = $baseUrl . $service;
    
    // Parameter handling
    if (count($params) > 0) {
        $url .= '?';
        foreach ($params as $key => $value) {
            $value = urlencode(urldecode($value));
            $url .= "$key=$value&";
        }
        $url = rtrim($url, '&');
    }
    
    // HTTP request using 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()
    ));
    
    // Response handling
    if (is_wp_error($response)) {
        return "Something went wrong: " . $response->get_error_message();
    } else {
        $result = json_decode($response['body']);
        // ... error handling and data processing
    }
}

Authentication Method

  • Header: x-apikey: {credential}
  • Method: GET requests (sent via wp_remote_post with GET method)
  • Content-Type: application/json

Available Endpoints

Based on code analysis throughout the plugin:

  1. search - Book search and ISBN lookup
  2. book/{isbn} - Individual book details
  3. predictive - Predictive search/autocomplete
  4. searchfilter - Filter options and values

TypeSense API Structure

Configuration Function

Located in includes/typesense-functions.php:168-190:

function supapress_set_typesense_client() {
    $apiKey = (string)get_option('typesense_api_key');
    $host = (string)get_option('typesense_host');
    
    if (empty($apiKey) && empty($host)) {
        return;
    }
    
    $client = new Client([
        'nodes' => [
            [
                'host' => $host,
                'port' => '',
                'protocol' => 'https'
            ]
        ],
        'api_key' => $apiKey,
        'connection_timeout_seconds' => 2
    ]);
    
    return $client;
}

Complete Curl Command Templates

Using Provided Credential: $SUPAFOLIO_API_KEY

1. Book Search by ISBN

curl -X GET "https://api.supafolio.com/v2/search?isbns=9781234567890&amount=100" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

2. Bulk ISBN Lookup

curl -X GET "https://api.supafolio.com/v2/search?isbns=9781234567890,9780987654321,9781111111111&amount=100" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

3. Predictive Search/Autocomplete

curl -X GET "https://api.supafolio.com/v2/predictive?keyword=javascript&amount=10&type=Products" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

4. Get Filter Values (e.g., book formats)

curl -X GET "https://api.supafolio.com/v2/searchfilter?filters=format" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

5. Collection Filter Values

curl -X GET "https://api.supafolio.com/v2/searchfilter?filters=collection" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

6. Book Details by ISBN

curl -X GET "https://api.supafolio.com/v2/book/9781234567890" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

7. Search with Collection Filter

curl -X GET "https://api.supafolio.com/v2/search?collection=fiction&amount=50" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

8. Search with Sorting

curl -X GET "https://api.supafolio.com/v2/search?keyword=programming&order=publishdate-desc&amount=25" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

Parameter Reference

Common Parameters

  • isbns - Comma-separated ISBN list for bulk lookups
  • amount - Number of results to return (default: 100)
  • collection - Collection name for filtering
  • keyword - Search term for text searches
  • order - Sort order options:
    • as-entered (default)
    • publishdate-desc (newest to oldest)
    • publishdate-asc (oldest to newest)
    • title-az (A to Z)
    • title-za (Z to A)
  • page - Pagination for large result sets
  • filters - Filter types for searchfilter endpoint (format, collection, etc.)
  • type - Content type (used with predictive search, e.g., "Products")

Advanced Parameters

  • Multiple ISBNs: Use comma-separated values
  • Price filtering: Available with specific currency parameters
  • Date ranges: For publication date filtering

Response Format Documentation

Success Response

{
    "status": "success",
    "data": {
        // Actual response data here
        // Varies by endpoint
    }
}

Error Response

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

Common Error Messages

  • "Product not in database"
  • "ISBN not found"
  • "Something went wrong: [specific error]"

Testing Strategy

Recommended Testing Sequence

  1. Authentication Test

    curl -X GET "https://api.supafolio.com/v2/searchfilter?filters=format" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

  2. Simple Book Search

    curl -X GET "https://api.supafolio.com/v2/search?isbns=9781234567890&amount=10" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

  3. Predictive Search Test

    curl -X GET "https://api.supafolio.com/v2/predictive?keyword=test&amount=5&type=Products" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"

Debugging Tips

  • Add ?debug parameter to WordPress URLs to see API call details
  • Check WordPress error logs for HTTP request failures
  • Verify API key is correctly configured in WordPress settings
  • Test with known valid ISBNs first

Plugin Configuration

WordPress Settings

The plugin uses these WordPress options:

  • service_url - Custom API endpoint URL
  • api_key - Custom API key (your credential would go here)
  • typesense_api_key - TypeSense API key
  • typesense_host - TypeSense host URL
  • typesense_catalog - TypeSense catalog name

Default Values

If no custom settings are provided:

  • URL: https://api.supafolio.com/v2/
  • API Key: 9819864f6ff0e8a5a097c99224cfd18a

Security Considerations

  • API key is sent in HTTP headers (more secure than URL parameters)
  • Plugin implements caching to reduce API calls
  • Supports both HTTP and HTTPS protocols
  • Custom service URLs can be configured for private deployments

Alternative: TypeSense API

If using TypeSense instead of Supafolio:

curl -X GET "https://{typesense-host}/collections/{catalog}/documents/search" \
  -H "x-typesense-api-key: $TYPESENSE_API_KEY" \
  -H "Content-Type: application/json"

Summary

The Supapress plugin provides comprehensive access to book metadata APIs through two main systems:

  1. Supafolio API (primary) - Full-featured book data service
  2. TypeSense API (alternative) - Search-focused service

Your credential $SUPAFOLIO_API_KEY can be used with either system, depending on your WordPress plugin configuration.

The curl commands provided above should give you complete access to test and interact with the API endpoints used by the Supapress plugin.

Generated: 2026-01-24
Plugin Version: 2.26.2
Analysis Scope: Supafolio API integration in Supapress WordPress plugin