General Guidelines for Hoopla Partner API Endpoint Use

The Hoopla Partner API Development Team has some general guidelines for partners to follow when calling our API endpoints. This will ensure everyone is maintaining an efficient process and appropriately accessing our API.

Request Debouncing

Add a debounce mechanism to delay API endpoint calls by 300-500ms after user input stops, or when the user presses enter.

Rate Limiting

Ensure the client does not exceed certain 100 requests per minute. For the Content Extraction endpoint specifically, less than 25 requests per minute is recommended.

Use exponential backoff on 429 errors.

Batch Processing

Partners requesting batch sizes well above what an endpoint is built to serve in one call (e.g. 1000 records/call against an endpoint tuned for 500) have historically led to socket timeouts and slow harvests.

Use bulk endpoints where available and limit batch sizes accordingly.

Implement pagination for large datasets.

Content Extraction
Full/delta content extraction
Recommended batch size (production): 500
Recommended batch size (staging): 125

Content Information
Batch status/availability check by ID
Recommended batch size (production): 50
Recommended batch size (staging): 12

Global Contents
Full/delta content extraction (country-scoped)
Recommended batch size (production): up to 1,000
Recommended batch size (staging): up to 250

Library Entitlements
Active/inactive status feed per contentId
Recommended batch size (production): up to 1,000 (default)
Recommended batch size (staging): up to 250 (default)

Caching

Cache search results, metadata, and static content with appropriate TTL values.

Implement cache invalidation policies to keep data fresh.

Deltas

Once you've initially extracted the full Hoopla data set, use deltas to call for title additions, removals, and metadata updates.

Both /content and /global-contents accept startTime for incremental (delta) sync. Full syncs should be rare (e.g. weekly at most, not a routine daily operation), use startTime (in UTC/Zulu format) set to your last successful sync timestamp for regular updates instead of re-pulling the entire catalog.

If a full/large sync fails partway through, resume from the last successful startToken (content ID starting point for pagination) rather than restarting from zero. This is especially important for syncs in the ~1M record range that can take many hours.

Error Handling

Log all errors, retry on 429 responses, and display helpful messages to end users (patrons).

200 - Success!

400 - Invalid request parameters. Don't retry as-is; fix the request.

401 - Unauthorized / token expired. Refresh token, then retry once.

5xx (incl. timeouts) - Transient backend issue. Retry with backoff. If failures cluster around large-batch or full-sync calls, reduce batch size and prefer delta sync.

Request Optimization

Use query parameters to narrow down data retrieval.

Implement conditional requests with If-Modified-Since headers.

Combine similar requests to reduce server calls.

Every list endpoint returns a continuation token. Use it to your advantage, don't recompute an offset:

• /content, /global-contents: response includes nextStartToken (or metadata.nextPageToken for Global Content) — pass that value back as startToken on the next call.
• /entitlements: same pattern via startToken.

Format Identification

Time must be in the standard ISO format using UTC (Zulu time).

We support a two-letter country code, they are as follows - US, CA, AU, NZ.

Performance Tuning

Adjust the batch size between 200–500* per request.

Decrease Hoopla holdings refresh to every other day*.

*actuals will be dependent on how your system behaves in production

Testing

We have migrated to OpenAPI and are asking our partners to do the same. Here is the new URL: https://api-docs.hoopladigital.com/partner/index.html#/

With this move comes a change to our testing process as well. The Hoopla Team are reserving our Dev Environment for internal testing and have moved our partner testing to our Staging Environment.

Staging runs on a fraction of production's compute and database resources, so it saturates at a much lower concurrent request volume. As a rule of thumb, use 1/4 of the production recommended batch size when testing or integrating against staging, and expect to see connection pool pressure or timeouts sooner than you would in production if you push staging past that. If you need to load-test at production-like volume, coordinate a dedicated window with the Product Discovery team rather than running it against shared staging.

For staging credentials, please email hdiscovery@midwesttape.com.

API Endpoint Issues and Developer Feedback

We always want to hear from our developer partners. If you are dealing with integration issues or have feedback to share, please email hdiscovery@midwesttape.com.