> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Integration tips for reliability and performance

## Networking

* Set reasonable timeouts (e.g., 10–30s) and retry on transient failures
* Use HTTPS only; verify certificates by default

## Authentication

* Store API keys securely (env vars, secret stores)
* Do not embed keys in client-side code or public repos

## Pagination & Memory

* Prefer paginated fetches over large single responses
* Stream or process items incrementally where possible
* Prefer scoped routes (`entities/byId`, `timeline/byOrganizationId`, `signal/top`) over bulk `/all` routes unless you genuinely need premium feed behavior

## Route Selection

* Start with `/v1/search` for most prototypes and first integrations
* Resolve stable Shoal entity ids with `/v1/entities/byName` before building recurring monitoring workflows
* Treat `/all` endpoints as premium bulk-feed surfaces, not as the default polling path
* Use `/v1/usage` and response headers to understand the route class and budget impact of each request
* Treat `/v1/organizations/*` as compatibility routes, not the primary integration path for new builds

## Observability

* Log request IDs and timestamps alongside responses
* Log `X-Api-Surface`, `X-Access-Layer`, and `X-Endpoint-Policy` if you are building a multi-endpoint integration
* Add a descriptive `User-Agent` (e.g., `your-app/1.2.3`)