Test Your SuperAPI Cache

Testing Your SuperAPI Gateway

Once your SuperAPI gateway shows as Healthy and your cache shows as active in the dashboard, it's ready to start caching your API responses. This section will guide you through testing your cache implementation and understanding the cache behavior through response headers.

Making API Calls Through SuperAPI

When calling your API through SuperAPI, you need to use the SuperAPI DNS endpoint instead of your origin server. This ensures your requests pass through the SuperAPI cache layer, allowing configured endpoints to benefit from caching before the request potentially reaches your origin server.

Required Headers for API Calls

The essential header for all SuperAPI requests is:

• SS4-HOST - The origin server hostname that SuperAPI should route to

For authentication:

• If you configured JWT token authorization when setting up SuperAPI, you must include that same authorization header in your requests
• If you selected "unauthenticated" during SuperAPI configuration, no authorization header is needed

Example API Call

Here's how to make a test API call through your SuperAPI gateway:

curl -I -X GET \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'SS4-HOST: api.your-origin-server.com' \
  'https://your-gateway.superapi.cloud/v2/candidate?job_id=007197d2-7c9e-4315-8f61-228ac02f3ecc&limit=200&offset=0&order_by=created_at'

In this example:

• https://your-gateway.superapi.cloud is your SuperAPI DNS endpoint
• api.your-origin-server.com is your origin server DNS specified in the SS4-HOST header

Understanding Cache Response Headers

SuperAPI adds specific headers to API responses that help you monitor cache performance and behavior.

Key Cache Headers

When your gateway is active, you'll see these important headers in API responses:

Cache Status Indicators

ss4-cache - Shows whether the response was served from cache or origin:

• HIT - Response was served from SuperAPI's cache without contacting your origin server
• MISS - Response required a call to your origin server and was then cached for future requests

ss4-cache-key - A unique identifier for this specific cached response, useful for debugging and cache management

Testing Cache Behavior

Verifying Cache Hits

To test if your cache is working correctly:

1. Make the first request - This should result in a MISS as the response gets cached
2. Make the same request again - This should result in a HIT as the response comes from cache
3. Check the response time - Cached responses should be significantly faster

To measure response time, add the -w flag to your curl command to display timing metrics:

# Add timing information to your curl request
curl -w "\nTotal time: %{time_total}s\n" -X GET \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN" \
  -H 'SS4-HOST: api.your-origin-server.com' \
  'https://your-gateway.superapi.cloud/api/users/123'

This will show the total request time in seconds, allowing you to compare cache HIT vs MISS performance.

Example Test Sequence

# First request - expect ss4-cache: MISS
curl -I -w "\nTotal time: %{time_total}s\n" -X GET \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN" \
  -H 'SS4-HOST: api.your-origin-server.com' \
  'https://your-gateway.superapi.cloud/api/users/123'
 
# Second request - expect ss4-cache: HIT
curl -I -w "\nTotal time: %{time_total}s\n" -X GET \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN" \
  -H 'SS4-HOST: api.your-origin-server.com' \
  'https://your-gateway.superapi.cloud/api/users/123'

Testing Cache Invalidation

To verify that your invalidate endpoints properly invalidate cache:

1. Make a GET request to cache a response (ss4-cache: HIT)
2. Make a Database Update to a relevant row that would invalidate the cache.
3. Repeat the GET request - should now show ss4-cache: MISS as cache was invalidated

When you see ss4-cache: MISS in the response, SuperAPI will also include an additional header ss4-cache-miss-reason that explains why the cache was missed:

• MISSING - The requested data was not found in the cache (typical for first-time requests)
• DATA CHANGED - The cache was invalidated due to a Update/Delete operation or database change

If you have configured invalidation APIs in SuperAPI, you can call these invalidate APIs to invalidate specific cache entries. Additionally, any direct database edits related to your Tables of Interest will also automatically invalidate the cache for affected endpoints.

Example Cache Invalidation Test

# Step 1: Cache a user profile
curl -I -X GET \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN" \
  -H 'SS4-HOST: api.your-origin-server.com' \
  'https://your-gateway.superapi.cloud/api/users/123'
# Expected: ss4-cache: HIT (after first call)
 
# Step 2: Update the user (invalidates cache)
curl -X PUT \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN" \
  -H 'SS4-HOST: api.your-origin-server.com' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Updated Name"}' \
  'https://your-gateway.superapi.cloud/api/users/123'
 
# Step 3: Request user profile again
curl -I -X GET \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN" \
  -H 'SS4-HOST: api.your-origin-server.com' \
  'https://your-gateway.superapi.cloud/api/users/123'
# Expected: ss4-cache: MISS with ss4-cache-miss-reason: DATA CHANGED (cache was invalidated)

Troubleshooting Common Issues

Cache Always Shows MISS

Possible causes:

• TTL set too low
• Parameters not properly mapped
• Request headers varying between calls

Cache Not Invalidating

Possible causes:

• Invalidate endpoint not configured
• Parameter relationships not matching between GET and Invalidate endpoints
• Tables of Interest not properly configured

Authentication Errors

Ensure your Authorization header includes the correct bearer token and that your SuperAPI credentials are valid.

Best Practices for Testing

1. Test with consistent parameters - Use the same exact URL and parameters when testing cache behavior
2. Monitor cache keys - Different cache keys indicate different cached responses
3. Test edge cases - Verify cache behavior with various parameter combinations
4. Document your tests - Keep track of which endpoints are configured and their expected cache behavior

By systematically testing your SuperAPI cache implementation, you can ensure optimal performance and verify that your caching strategy works as intended across all configured endpoints.