# Strapi Authentication Examples

> JWT authentication, user registration, login, and authenticated requests. See [SKILL.md](../SKILL.md) for core concepts and [core.md](core.md) for REST API patterns.

**Prerequisites**: Understand REST API request/response format from core examples first.

---

## Pattern 1: User Registration

### Good Example -- Register with Error Handling

```typescript
const STRAPI_URL = process.env.STRAPI_URL;

interface AuthResponse {
  jwt: string;
  refreshToken?: string;
  user: {
    id: number;
    documentId: string;
    username: string;
    email: string;
  };
}

async function registerUser(
  username: string,
  email: string,
  password: string,
): Promise<AuthResponse> {
  const response = await fetch(`${STRAPI_URL}/api/auth/local/register`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ username, email, password }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || "Registration failed");
  }

  return response.json();
}

// Usage
const { jwt, user } = await registerUser(
  "jane",
  "jane@example.com",
  "SecurePass123!",
);
// jwt: "eyJhbGciOi..." -- store securely
// user: { id: 1, documentId: "...", username: "jane", email: "jane@example.com" }
```

**Why good:** Registration endpoint returns JWT immediately (user is logged in after register), error response parsed for descriptive messages, typed response interface

---

## Pattern 2: User Login

### Good Example -- Login with JWT Storage

```typescript
async function loginUser(
  identifier: string, // Email or username
  password: string,
): Promise<AuthResponse> {
  const response = await fetch(`${STRAPI_URL}/api/auth/local`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ identifier, password }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || "Login failed");
  }

  return response.json();
}

// Usage
const { jwt, refreshToken, user } = await loginUser(
  "jane@example.com",
  "SecurePass123!",
);
```

**Why good:** `identifier` accepts either email or username, returns JWT and optional refresh token (depends on `jwtManagement` config), typed response

### Bad Example -- Insecure Token Storage

```typescript
// BAD: Storing JWT in localStorage (XSS-vulnerable)
const { jwt } = await loginUser("jane@example.com", "pass");
localStorage.setItem("jwt", jwt); // Accessible by any script on the page
```

**Why bad:** `localStorage` is accessible to any JavaScript on the page (XSS vulnerability), consider httpOnly cookies or secure session management for production

---

## Pattern 3: Authenticated Requests

### Good Example -- Bearer Token in Headers

```typescript
async function fetchProtectedData<T>(path: string, token: string): Promise<T> {
  const response = await fetch(`${STRAPI_URL}${path}`, {
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
  });

  if (response.status === 401) {
    throw new Error("Authentication expired -- please login again");
  }

  if (!response.ok) {
    throw new Error(`Request failed: ${response.statusText}`);
  }

  return response.json();
}

// Fetch current user profile
const me = await fetchProtectedData("/api/users/me", jwt);

// Fetch protected content
const drafts = await fetchProtectedData(`/api/articles?status=draft`, jwt);
```

**Why good:** JWT passed in `Authorization: Bearer` header (Strapi convention), 401 handled separately for auth-specific error flow, reusable for any protected endpoint, `/api/users/me` returns the authenticated user

---

## Pattern 4: Token Refresh

### Good Example -- Refresh Token Flow

```typescript
async function refreshAccessToken(refreshToken: string): Promise<AuthResponse> {
  const response = await fetch(`${STRAPI_URL}/api/auth/refresh`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ refreshToken }),
  });

  if (!response.ok) {
    throw new Error("Token refresh failed -- please login again");
  }

  return response.json();
}

// Usage: Auto-refresh on 401
async function fetchWithRefresh<T>(
  path: string,
  accessToken: string,
  refreshToken: string,
): Promise<{ data: T; newTokens?: { jwt: string; refreshToken: string } }> {
  try {
    const data = await fetchProtectedData<T>(path, accessToken);
    return { data };
  } catch (error) {
    if (
      error instanceof Error &&
      error.message.includes("Authentication expired")
    ) {
      // Attempt refresh
      const newAuth = await refreshAccessToken(refreshToken);
      const data = await fetchProtectedData<T>(path, newAuth.jwt);
      return {
        data,
        newTokens: { jwt: newAuth.jwt, refreshToken: newAuth.refreshToken! },
      };
    }
    throw error;
  }
}
```

**Why good:** Refresh flow only triggers on 401 (expired token), returns new tokens to the caller for storage, falls through to re-throw for non-auth errors

**Note:** Token refresh requires `jwtManagement: 'refresh'` in the Users & Permissions plugin config. The default `'legacy-support'` mode does not support refresh tokens.

---

## Pattern 5: API Token Authentication (Server-to-Server)

### Good Example -- Using API Tokens

```typescript
// For server-to-server or script access (not end-user auth)
const API_TOKEN = process.env.STRAPI_API_TOKEN;

async function fetchWithApiToken<T>(path: string): Promise<T> {
  const response = await fetch(`${STRAPI_URL}${path}`, {
    headers: {
      Authorization: `Bearer ${API_TOKEN}`,
    },
  });

  if (!response.ok) {
    throw new Error(`API request failed: ${response.statusText}`);
  }

  return response.json();
}
```

**Why good:** API tokens are created in the admin panel (Settings > API Tokens), suitable for server-to-server communication, CI/CD scripts, and static site generation where user login is inappropriate

**API Token types:**

- **Read-only** -- Can only `find` and `findOne`
- **Full access** -- All CRUD operations on all content types
- **Custom** -- Fine-grained per-content-type, per-action permissions

---

## Pattern 6: Permissions Configuration

### Configuring Public Access

Permissions are set in the Strapi admin panel under **Settings > Users & Permissions plugin > Roles**.

```
Admin Panel > Settings > Users & Permissions > Roles > Public
  - Application
    - Article
      - [x] find       (GET /api/articles)
      - [x] findOne    (GET /api/articles/:documentId)
      - [ ] create     (POST /api/articles)
      - [ ] update     (PUT /api/articles/:documentId)
      - [ ] delete     (DELETE /api/articles/:documentId)
```

### Configuring Authenticated Access

```
Admin Panel > Settings > Users & Permissions > Roles > Authenticated
  - Application
    - Article
      - [x] find
      - [x] findOne
      - [x] create
      - [x] update
      - [x] delete
```

### JWT Configuration

```typescript
// config/plugins.ts
export default ({ env }) => ({
  "users-permissions": {
    config: {
      jwt: {
        expiresIn: "7d", // Access token expiration
      },
      jwtManagement: "refresh", // Enable refresh tokens
      // or 'legacy-support' for simple JWT (no refresh)
    },
  },
});
```

**Why good:** JWT expiration configured via plugin config (not hardcoded), `jwtManagement: 'refresh'` enables the modern refresh token flow, permissions managed declaratively in the admin panel

---

_For REST API patterns, see [core.md](core.md). For backend customization, see [backend.md](backend.md)._

# Strapi Backend Customization Examples

> Custom controllers, services, routes, policies, middlewares, and lifecycle hooks. See [SKILL.md](../SKILL.md) for core concepts and [core.md](core.md) for REST API and Document Service patterns.

**Prerequisites**: Understand the Document Service API from core examples first.

---

## Pattern 1: Custom Controller with Sanitization

### Good Example -- Extending Core Controller

```typescript
// src/api/article/controllers/article.ts
import { factories } from "@strapi/strapi";

export default factories.createCoreController(
  "api::article.article",
  ({ strapi }) => ({
    // Override default find with additional logic
    async find(ctx) {
      await this.validateQuery(ctx);
      const sanitizedQuery = await this.sanitizeQuery(ctx);

      const { results, pagination } = await strapi
        .service("api::article.article")
        .find(sanitizedQuery);

      const sanitizedResults = await this.sanitizeOutput(results, ctx);
      return this.transformResponse(sanitizedResults, { pagination });
    },

    // Custom action: find article by slug
    async findBySlug(ctx) {
      const { slug } = ctx.params;

      const article = await strapi.documents("api::article.article").findFirst({
        filters: { slug: { $eq: slug } },
        status: "published",
        populate: { author: true, categories: true, cover: true },
      });

      if (!article) {
        return ctx.notFound("Article not found");
      }

      const sanitized = await this.sanitizeOutput(article, ctx);
      return this.transformResponse(sanitized);
    },

    // Custom action: increment view count
    async incrementViews(ctx) {
      const { documentId } = ctx.params;
      const CONTENT_TYPE_UID = "api::article.article";

      const article = await strapi.documents(CONTENT_TYPE_UID).findOne({
        documentId,
        fields: ["viewCount"],
      });

      if (!article) {
        return ctx.notFound("Article not found");
      }

      const updated = await strapi.documents(CONTENT_TYPE_UID).update({
        documentId,
        data: { viewCount: (article.viewCount || 0) + 1 },
      });

      const sanitized = await this.sanitizeOutput(updated, ctx);
      return this.transformResponse(sanitized);
    },
  }),
);
```

**Why good:** `validateQuery` throws on invalid query params, `sanitizeQuery` strips fields the user's role can't access, `sanitizeOutput` removes private fields from the response, `transformResponse` wraps output in the standard `{ data, meta }` envelope, `ctx.notFound()` returns proper 404

### Bad Example -- No Sanitization

```typescript
// BAD: Bypasses all permission checks
async find(ctx) {
  const articles = await strapi.documents("api::article.article").findMany({
    populate: "*",
  });
  return { data: articles }; // Exposes private fields, no permission enforcement
}
```

**Why bad:** Skips `sanitizeQuery`, `sanitizeOutput`, and `validateQuery`, which means private fields are exposed and role-based field restrictions are bypassed

---

## Pattern 2: Custom Controller for Non-CRUD Operations

### Good Example -- Custom Business Logic Controller

```typescript
// src/api/article/controllers/article.ts (continued)
import { factories } from "@strapi/strapi";

export default factories.createCoreController(
  "api::article.article",
  ({ strapi }) => ({
    // Custom: Search across multiple fields
    async search(ctx) {
      const { query: searchTerm } = ctx.request.query;

      if (!searchTerm || typeof searchTerm !== "string") {
        return ctx.badRequest("Query parameter 'query' is required");
      }

      const articles = await strapi.documents("api::article.article").findMany({
        status: "published",
        filters: {
          $or: [
            { title: { $containsi: searchTerm } },
            { body: { $containsi: searchTerm } },
          ],
        },
        populate: { author: { fields: ["name"] } },
        sort: [{ publishedAt: "desc" }],
        pagination: { page: 1, pageSize: 20 },
      });

      const sanitized = await this.sanitizeOutput(articles, ctx);
      return this.transformResponse(sanitized);
    },
  }),
);
```

**Why good:** Validates input before querying, `$containsi` for case-insensitive search, `$or` searches across multiple fields, pagination prevents unbounded results, output sanitized

---

## Pattern 3: Custom Routes

### Good Example -- Registering Custom Routes

```typescript
// src/api/article/routes/custom-article.ts
export default {
  routes: [
    {
      method: "GET",
      path: "/articles/slug/:slug",
      handler: "api::article.article.findBySlug",
      config: {
        auth: false, // Public route
      },
    },
    {
      method: "POST",
      path: "/articles/:documentId/views",
      handler: "api::article.article.incrementViews",
      config: {
        auth: false, // Public (no login needed to increment views)
      },
    },
    {
      method: "GET",
      path: "/articles/search",
      handler: "api::article.article.search",
      config: {
        auth: false,
        policies: [],
        middlewares: [],
      },
    },
  ],
};
```

### Good Example -- Restricting Core Routes

```typescript
// src/api/article/routes/article.ts
import { factories } from "@strapi/strapi";

export default factories.createCoreRouter("api::article.article", {
  // Only expose find and findOne (disable create/update/delete via REST)
  only: ["find", "findOne"],
  config: {
    find: {
      auth: false, // Public listing
      middlewares: ["api::article.populate-defaults"],
    },
    findOne: {
      auth: false, // Public detail
    },
  },
});
```

**Why good:** Core router with `only` limits exposed endpoints (disabling write operations via REST), per-action config applies middlewares and auth settings, custom routes in a separate file to avoid conflicts

---

## Pattern 4: Route Middleware

### Good Example -- Default Population Middleware

```typescript
// src/api/article/middlewares/populate-defaults.ts
export default (config, { strapi }) => {
  return async (ctx, next) => {
    // Set default population if none provided
    if (!ctx.query.populate) {
      ctx.query.populate = {
        author: { fields: ["name"] },
        categories: { fields: ["name", "slug"] },
        cover: { fields: ["url", "alternativeText"] },
      };
    }

    await next();
  };
};
```

**Why good:** Middleware sets sensible default population so consumers don't need to specify it every time, only applies when no populate is explicitly provided, passes through to the next middleware/controller via `await next()`

---

## Pattern 5: Policies

### Good Example -- Owner-Only Policy

```typescript
// src/api/article/policies/is-owner.ts
export default async (policyContext, config, { strapi }) => {
  const user = policyContext.state.user;

  if (!user) {
    return false; // Not authenticated
  }

  const { documentId } = policyContext.params;

  const article = await strapi.documents("api::article.article").findOne({
    documentId,
    populate: { author: true },
  });

  if (!article) {
    return false; // Document not found
  }

  // Only allow if the authenticated user is the author
  return article.author?.documentId === user.documentId;
};
```

### Good Example -- Rate Limit Policy

```typescript
// src/policies/rate-limit.ts
const MAX_REQUESTS_PER_MINUTE = 60;
const requestCounts = new Map<string, { count: number; resetAt: number }>();

export default async (policyContext, config) => {
  const ip = policyContext.request.ip;
  const now = Date.now();
  const limit = config?.limit || MAX_REQUESTS_PER_MINUTE;
  const windowMs = config?.windowMs || 60_000;

  const entry = requestCounts.get(ip);

  if (!entry || now > entry.resetAt) {
    requestCounts.set(ip, { count: 1, resetAt: now + windowMs });
    return true;
  }

  if (entry.count >= limit) {
    return false; // Rate limited
  }

  entry.count += 1;
  return true;
};
```

### Applying Policies to Routes

```typescript
// In core router config
export default factories.createCoreRouter("api::article.article", {
  config: {
    update: {
      policies: ["api::article.is-owner"],
    },
    delete: {
      policies: ["api::article.is-owner"],
    },
  },
});

// In custom routes
{
  method: "POST",
  path: "/articles/:documentId/publish",
  handler: "api::article.article.publishArticle",
  config: {
    policies: [
      "api::article.is-owner",
      { name: "global::rate-limit", config: { limit: 10 } },
    ],
  },
}
```

**Why good:** Policies return `true`/`false` (read-only, cannot modify request), inline config passed to configurable policies, multiple policies chain together (all must pass)

---

## Pattern 6: Lifecycle Hooks

### Good Example -- Content Type Lifecycle

```typescript
// src/api/article/content-types/article/lifecycles.ts
export default {
  async beforeCreate(event) {
    const { data } = event.params;

    // Auto-generate slug if not provided
    if (data.title && !data.slug) {
      data.slug = data.title
        .toLowerCase()
        .replace(/[^a-z0-9]+/g, "-")
        .replace(/^-|-$/g, "");
    }
  },

  async afterCreate(event) {
    const { result } = event;
    strapi.log.info(
      `Article created: ${result.documentId} - "${result.title}"`,
    );
  },

  async beforeUpdate(event) {
    const { data } = event.params;

    // Trim title whitespace
    if (data.title) {
      data.title = data.title.trim();
    }
  },

  async afterDelete(event) {
    const { result } = event;
    strapi.log.info(`Article deleted: ${result.documentId}`);
    // Cleanup: remove from search index, invalidate cache, etc.
  },
};
```

**Why good:** `beforeCreate` can mutate `event.params.data` to transform input, `afterCreate` has access to `event.result` (the created document), lifecycle hooks run for both REST API and Document Service operations, logging for audit trail

### Good Example -- Programmatic Lifecycle Subscription

```typescript
// src/index.ts -- Register in bootstrap
export default {
  async bootstrap({ strapi }) {
    strapi.db.lifecycles.subscribe({
      models: ["api::article.article"],

      async afterCreate(event) {
        const { result } = event;
        // Send notification, update analytics, etc.
      },
    });
  },
};
```

**Why good:** Programmatic subscription allows subscribing to multiple content types from a single location, useful for cross-cutting concerns like audit logging or search indexing

---

## Pattern 7: Custom Services

### Good Example -- Service with Complex Business Logic

```typescript
// src/api/article/services/article.ts
import { factories } from "@strapi/strapi";

const CONTENT_TYPE_UID = "api::article.article";
const MAX_RELATED_ARTICLES = 5;

export default factories.createCoreService(CONTENT_TYPE_UID, ({ strapi }) => ({
  async findRelated(documentId: string) {
    const article = await strapi.documents(CONTENT_TYPE_UID).findOne({
      documentId,
      populate: { categories: true },
    });

    if (!article?.categories?.length) {
      return [];
    }

    const categoryIds = article.categories.map((c) => c.documentId);

    return strapi.documents(CONTENT_TYPE_UID).findMany({
      status: "published",
      filters: {
        documentId: { $ne: documentId }, // Exclude current article
        categories: { documentId: { $in: categoryIds } },
      },
      sort: [{ publishedAt: "desc" }],
      pagination: { page: 1, pageSize: MAX_RELATED_ARTICLES },
      populate: { cover: { fields: ["url", "alternativeText"] } },
    });
  },

  async publishAndNotify(documentId: string) {
    const result = await strapi.documents(CONTENT_TYPE_UID).publish({
      documentId,
    });

    // Trigger side effects after publishing
    const article = await strapi.documents(CONTENT_TYPE_UID).findOne({
      documentId,
      status: "published",
      populate: { author: true },
    });

    strapi.log.info(`Article published: ${article?.title}`);

    return result;
  },
}));
```

**Why good:** Service encapsulates reusable business logic, named constant for limit, `$ne` filter excludes the current document, `$in` matches any of the category IDs, called from controllers via `strapi.service('api::article.article').findRelated(id)`

---

## Pattern 8: Document Service Middleware

Document Service middleware is the recommended v5 approach for intercepting content operations. It provides more predictable behavior than database lifecycle hooks, especially with draft/publish workflows.

### Good Example -- Audit Logging Middleware

```typescript
// src/index.ts
export default {
  register({ strapi }) {
    strapi.documents.use(async (ctx, next) => {
      const result = await next();

      if (
        ["create", "update", "delete", "publish", "unpublish"].includes(
          ctx.action,
        )
      ) {
        strapi.log.info(
          `[audit] ${ctx.action} on ${ctx.uid} by user ${ctx.params?.data?.updatedBy || "system"}`,
        );
      }

      return result;
    });
  },
};
```

**Why good:** Registered in `register()` (not `bootstrap()`), intercepts all Document Service operations, logs after the operation completes (uses `await next()`), filters by action type to avoid noisy find/count logs

### Good Example -- Default Populate Middleware

```typescript
// src/index.ts
export default {
  register({ strapi }) {
    strapi.documents.use(async (ctx, next) => {
      if (ctx.uid === "api::article.article" && ctx.action === "findMany") {
        ctx.params = {
          ...ctx.params,
          populate: ctx.params?.populate ?? { author: true, categories: true },
        };
      }

      return next();
    });
  },
};
```

**Why good:** Modifies params before the operation (`next()` called after), only applies to a specific content type and action, preserves explicitly-set populate params via nullish coalescing

---

_For REST API and Document Service patterns, see [core.md](core.md). For authentication, see [auth.md](auth.md)._

# Strapi Core Examples

> Content type schemas, REST API querying, Document Service API, and error handling. See [SKILL.md](../SKILL.md) for core concepts.

**Backend customization:** See [backend.md](backend.md). **Authentication:** See [auth.md](auth.md).

---

## Pattern 1: Content Type Schemas

### Good Example -- Collection Type

```json
{
  "kind": "collectionType",
  "collectionName": "articles",
  "info": {
    "singularName": "article",
    "pluralName": "articles",
    "displayName": "Article",
    "description": "Blog articles"
  },
  "options": {
    "draftAndPublish": true
  },
  "attributes": {
    "title": {
      "type": "string",
      "required": true,
      "maxLength": 120
    },
    "slug": {
      "type": "uid",
      "targetField": "title"
    },
    "body": {
      "type": "richtext"
    },
    "cover": {
      "type": "media",
      "allowedTypes": ["images"],
      "multiple": false
    },
    "author": {
      "type": "relation",
      "relation": "manyToOne",
      "target": "api::author.author",
      "inversedBy": "articles"
    },
    "categories": {
      "type": "relation",
      "relation": "manyToMany",
      "target": "api::category.category",
      "inversedBy": "articles"
    },
    "seo": {
      "type": "component",
      "component": "shared.seo",
      "required": false
    },
    "blocks": {
      "type": "dynamiczone",
      "components": ["blocks.hero", "blocks.rich-text", "blocks.gallery"]
    }
  }
}
```

**Why good:** `draftAndPublish: true` enables draft/publish workflow, `uid` auto-generates slugs from `targetField`, `media` restricts to images, relation types define cardinality with `inversedBy`, component and dynamic zone fields compose reusable blocks

### Good Example -- Single Type

```json
{
  "kind": "singleType",
  "collectionName": "site_settings",
  "info": {
    "singularName": "site-setting",
    "pluralName": "site-settings",
    "displayName": "Site Settings"
  },
  "attributes": {
    "siteName": {
      "type": "string",
      "required": true
    },
    "logo": {
      "type": "media",
      "allowedTypes": ["images"]
    },
    "defaultSeo": {
      "type": "component",
      "component": "shared.seo"
    }
  }
}
```

**Why good:** `singleType` creates a single-document endpoint (`GET /api/site-setting`) for global config like site settings, navigation, or footer content

---

## Pattern 2: REST API -- Fetching with qs

### Good Example -- Typed Fetch with Filters, Populate, and Pagination

```typescript
import qs from "qs";

const STRAPI_URL = process.env.STRAPI_URL;
const DEFAULT_PAGE_SIZE = 25;

interface StrapiResponse<T> {
  data: T;
  meta: {
    pagination?: {
      page: number;
      pageSize: number;
      pageCount: number;
      total: number;
    };
  };
}

interface Article {
  id: number;
  documentId: string;
  title: string;
  slug: string;
  publishedAt: string | null;
  author?: { id: number; documentId: string; name: string };
  categories?: Array<{
    id: number;
    documentId: string;
    name: string;
    slug: string;
  }>;
  cover?: {
    url: string;
    alternativeText: string;
    width: number;
    height: number;
  };
}

async function fetchArticles(
  page = 1,
  pageSize = DEFAULT_PAGE_SIZE,
): Promise<StrapiResponse<Article[]>> {
  const query = qs.stringify(
    {
      filters: {
        publishedAt: { $notNull: true },
      },
      populate: {
        author: { fields: ["name"] },
        categories: { fields: ["name", "slug"] },
        cover: { fields: ["url", "alternativeText", "width", "height"] },
      },
      sort: ["publishedAt:desc"],
      pagination: { page, pageSize },
    },
    { encodeValuesOnly: true },
  );

  const response = await fetch(`${STRAPI_URL}/api/articles?${query}`);

  if (!response.ok) {
    throw new Error(
      `Failed to fetch articles: ${response.status} ${response.statusText}`,
    );
  }

  return response.json();
}
```

**Why good:** `qs.stringify` with `encodeValuesOnly` handles nested params correctly, targeted populate with field selection avoids over-fetching, named constant for page size, typed response interface matches v5 flat format, error handling for non-OK responses

### Bad Example -- Manual Query String

```typescript
// BAD: Manual query string construction
const url = `/api/articles?populate=*&filters[title][$contains]=${userInput}`;
const data = await fetch(url).then((r) => r.json());
```

**Why bad:** `populate=*` over-fetches all relations (security risk), user input not encoded (XSS/injection), no error handling, missing pagination leads to unbounded result sets

---

## Pattern 3: REST API -- Complex Filters

### Good Example -- Logical Operators with qs

```typescript
// Find articles in "tech" OR "science" categories, published after a date
const MIN_DATE = "2025-01-01";

const query = qs.stringify(
  {
    filters: {
      $and: [
        { publishedAt: { $gte: MIN_DATE } },
        {
          $or: [
            { categories: { slug: { $eq: "technology" } } },
            { categories: { slug: { $eq: "science" } } },
          ],
        },
      ],
    },
    populate: {
      categories: { fields: ["name", "slug"] },
    },
    sort: ["publishedAt:desc"],
    pagination: { page: 1, pageSize: 10 },
  },
  { encodeValuesOnly: true },
);
```

**Why good:** `$and` and `$or` compose complex queries, relation fields can be filtered directly, named constant for the date threshold, pagination prevents unbounded results

---

## Pattern 4: REST API -- Fetching Single Document by Slug

### Good Example -- Find by Slug with Deep Population

```typescript
async function fetchArticleBySlug(slug: string): Promise<Article | null> {
  const query = qs.stringify(
    {
      filters: { slug: { $eq: slug } },
      populate: {
        author: { fields: ["name", "email"] },
        categories: { fields: ["name", "slug"] },
        cover: { fields: ["url", "alternativeText", "width", "height"] },
        seo: { populate: "*" }, // Component population
        blocks: {
          on: {
            "blocks.hero": { populate: { background: { fields: ["url"] } } },
            "blocks.rich-text": { populate: "*" },
            "blocks.gallery": {
              populate: { images: { fields: ["url", "alternativeText"] } },
            },
          },
        },
      },
    },
    { encodeValuesOnly: true },
  );

  const response = await fetch(`${STRAPI_URL}/api/articles?${query}`);

  if (!response.ok) {
    throw new Error(`Failed to fetch article: ${response.status}`);
  }

  const { data } = await response.json();
  return data.length > 0 ? data[0] : null;
}
```

**Why good:** Filters by slug to get a specific article, component populated via nested populate, dynamic zone uses `on` syntax to populate per-component type, returns `null` when not found instead of crashing, separate field selection per relation

---

## Pattern 5: REST API -- Creating and Updating

### Good Example -- Create a Document

```typescript
async function createArticle(
  articleData: { title: string; body: string; slug: string },
  token: string,
): Promise<Article> {
  const response = await fetch(`${STRAPI_URL}/api/articles`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ data: articleData }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(
      `Failed to create article: ${error.error?.message || response.statusText}`,
    );
  }

  const { data } = await response.json();
  return data;
}
```

### Good Example -- Update a Document

```typescript
async function updateArticle(
  documentId: string,
  updates: Partial<{ title: string; body: string }>,
  token: string,
): Promise<Article> {
  const response = await fetch(`${STRAPI_URL}/api/articles/${documentId}`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ data: updates }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(
      `Failed to update article: ${error.error?.message || response.statusText}`,
    );
  }

  const { data } = await response.json();
  return data;
}
```

**Why good:** Request body wraps fields in `data` (required by Strapi), `Authorization: Bearer` header for JWT, error response parsed for descriptive error messages, `PUT` for updates uses `documentId` in the URL path

### Bad Example -- Missing Data Wrapper

```typescript
// BAD: Fields not wrapped in data object
await fetch(`${STRAPI_URL}/api/articles`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ title: "New Article", body: "Content..." }),
  // Missing: { data: { title: "...", body: "..." } }
});
```

**Why bad:** Strapi expects request body in `{ data: { ...fields } }` format, sending fields at the top level results in empty document creation

---

## Pattern 6: REST API -- Delete and Media Upload

### Good Example -- Delete Document

```typescript
async function deleteArticle(documentId: string, token: string): Promise<void> {
  const response = await fetch(`${STRAPI_URL}/api/articles/${documentId}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${token}` },
  });

  if (!response.ok && response.status !== 204) {
    throw new Error(`Failed to delete article: ${response.statusText}`);
  }
}
```

### Good Example -- Upload Media

```typescript
async function uploadMedia(file: File, token: string) {
  const formData = new FormData();
  formData.append("files", file);

  const response = await fetch(`${STRAPI_URL}/api/upload`, {
    method: "POST",
    headers: { Authorization: `Bearer ${token}` },
    // No Content-Type header -- FormData sets it with boundary
    body: formData,
  });

  if (!response.ok) {
    throw new Error(`Failed to upload: ${response.statusText}`);
  }

  const uploadedFiles = await response.json();
  return uploadedFiles[0]; // Returns array of uploaded files
}

// Link uploaded media to a document
async function setArticleCover(
  documentId: string,
  mediaId: number,
  token: string,
) {
  await fetch(`${STRAPI_URL}/api/articles/${documentId}`, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ data: { cover: mediaId } }),
  });
}
```

**Why good:** DELETE returns 204 with no body (handle accordingly), media upload uses FormData without explicit Content-Type header, uploaded file ID used to link media to a content field

---

## Pattern 7: Document Service API -- Server-Side CRUD

### Good Example -- Service with Document Service API

```typescript
// src/api/article/services/article.ts
import { factories } from "@strapi/strapi";

const CONTENT_TYPE_UID = "api::article.article";

export default factories.createCoreService(CONTENT_TYPE_UID, ({ strapi }) => ({
  async findPublished(filters = {}) {
    return strapi.documents(CONTENT_TYPE_UID).findMany({
      status: "published",
      filters,
      populate: { author: true, categories: true },
      sort: [{ publishedAt: "desc" }],
    });
  },

  async findBySlug(slug: string) {
    const article = await strapi.documents(CONTENT_TYPE_UID).findFirst({
      filters: { slug: { $eq: slug } },
      status: "published",
      populate: { author: true, categories: true, cover: true },
    });

    return article; // null if not found
  },

  async publishArticle(documentId: string) {
    return strapi.documents(CONTENT_TYPE_UID).publish({ documentId });
  },
}));
```

**Why good:** `createCoreService` inherits default CRUD methods, custom methods use Document Service for type-safe access, `status: 'published'` explicitly requests published content, `findFirst()` returns single document or null

### Bad Example -- Using Entity Service (v4 API)

```typescript
// BAD: Entity Service is removed in Strapi v5
const articles = await strapi.entityService.findMany("api::article.article", {
  filters: { publishedAt: { $notNull: true } },
  populate: { author: true },
});
```

**Why bad:** `strapi.entityService` does not exist in Strapi v5, use `strapi.documents()` instead

---

## Pattern 8: Error Handling

### Good Example -- Consistent Error Handling for REST API

```typescript
class StrapiError extends Error {
  status: number;
  details: unknown;

  constructor(message: string, status: number, details?: unknown) {
    super(message);
    this.name = "StrapiError";
    this.status = status;
    this.details = details;
  }
}

async function strapiRequest<T>(
  path: string,
  options: RequestInit = {},
): Promise<StrapiResponse<T>> {
  const url = `${STRAPI_URL}${path}`;
  const response = await fetch(url, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  if (!response.ok) {
    const errorBody = await response.json().catch(() => null);
    throw new StrapiError(
      errorBody?.error?.message || `Request failed: ${response.statusText}`,
      response.status,
      errorBody?.error?.details,
    );
  }

  // DELETE returns 204 with no body
  if (response.status === 204) {
    return { data: null as T, meta: {} };
  }

  return response.json();
}
```

**Why good:** Custom error class preserves HTTP status and Strapi error details, handles 204 (no body) from DELETE operations, reusable for all REST API calls, Strapi error format (`error.message`, `error.details`) extracted

---

_For backend customization patterns, see [backend.md](backend.md). For authentication, see [auth.md](auth.md)._