Best Practices

Recommended patterns for using the Dev API safely and efficiently.

Never Hardcode API Keys

Store your API key in environment variables, never in source code.

Astro

# .env
WHITEPAPPER_API_KEY=wp_your_api_key_here
PUBLIC_API_BASE_URL=https://whitepapper.antk.in/api

Next.js

# .env.local
WHITEPAPPER_API_KEY=wp_your_api_key_here
NEXT_PUBLIC_API_BASE_URL=https://whitepapper.antk.in/api

Node.js / Generic

export WHITEPAPPER_API_KEY=wp_your_api_key_here

const apiKey = process.env.WHITEPAPPER_API_KEY;

Edge Caching

Whitepapper already caches Dev API responses at the edge via Cloudflare. Response times are typically under 50ms for cached responses.

To maximize cache hits:

• Use GET requests (the API is read-only).
• Avoid unique query parameters on every request (they create cache misses).
• Reuse slugs and IDs — repeated requests for the same resource hit cache.

Application-Level Caching

For frontend frameworks that support page-level caching, add cache headers to your pages that consume Dev API data.

Astro

---
Astro.response.headers.set(
  "Cache-Control",
  "public, max-age=600, s-maxage=600, stale-while-revalidate=600",
);
---

Next.js (App Router)

// app/page.tsx
export const revalidate = 600; // seconds

Next.js (Pages Router)

export async function getStaticProps() {
  const data = await fetch("https://whitepapper.antk.in/api/dev/project", {
    headers: { "x-api-key": process.env.WHITEPAPPER_API_KEY },
  });
  return {
    props: { data: await data.json() },
    revalidate: 600,
  };
}

Error Handling

Always handle error responses from the Dev API:

const response = await fetch("https://whitepapper.antk.in/api/dev/project", {
  headers: { "x-api-key": apiKey },
});

if (!response.ok) {
  switch (response.status) {
    case 401:
      // Missing or invalid API key
      break;
    case 403:
      // Inactive key or wrong project scope
      break;
    case 404:
      // Resource not found
      break;
    case 429:
      // Monthly quota exceeded
      break;
  }
}

const data = await response.json();

Performance

• Dev API responses are paginated — use limit and cursor to control payload size.
• Omit body and metadata when listing papers if you only need titles and slugs (includeBody=false, includeMetadata=false).
• Use resolve_slug_to_id followed by get_paper_by_id when you need a single paper's full body.

Security

• The API key hashes are stored server-side. Whitepapper cannot recover a lost key.
• If a key is compromised, reset it immediately from the project API tab.
• For browser-based usage, consider proxying through your own server if you prefer not to expose the key client-side.

Related

• Dev API Quickstart — First API call.
• Authentication — Header contract and error codes.
• Caching and Errors — Cache behavior and troubleshooting.