git:20260320.7c261c3 to git:20260328.3208c13

---

name: api-cms-strapi

description: Open-source headless CMS — content type schemas, REST API, Document Service API, custom controllers, lifecycle hooks, authentication, TypeScript

---

# Strapi Patterns

> **Quick Guide:** Use Strapi as an open-source headless CMS with auto-generated REST/GraphQL APIs from content type schemas. In v5, use the Document Service API (`strapi.documents()`) for back-end data access instead of the deprecated Entity Service. REST API responses use a flat format (`data.fieldName`, not `data.attributes.fieldName`). Relations and media are NOT populated by default -- always pass `populate`. Use `qs` to build complex query strings. Content types are private by default; configure permissions via the Users & Permissions plugin or API tokens.

---

<critical_requirements>

## CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `strapi.documents('api::content-type.content-type')` (Document Service API) for all back-end data access in Strapi v5 -- the Entity Service API is removed)**

**(You MUST always pass `populate` when you need relations, media, components, or dynamic zones -- Strapi returns NO relations by default)**

**(You MUST use the `qs` library to build complex REST API query strings with filters, populate, and sort -- manual string construction breaks with nested params)**

**(You MUST sanitize and validate both input and output in custom controllers using `this.sanitizeQuery(ctx)`, `this.sanitizeOutput()`, and `this.validateQuery(ctx)`)**

**(You MUST set permissions for every content type endpoint via the admin panel or config -- all routes are private by default)**

</critical_requirements>

---

**Auto-detection:** Strapi, strapi, @strapi/strapi, createCoreController, createCoreService, createCoreRouter, Document Service, strapi.documents, content-type, schema.json, api::, plugin::, lifecycle hooks, Users & Permissions, /api/auth/local, populate, qs.stringify

**When to use:**

- Building content-managed applications with Strapi as the headless CMS

- Defining content type schemas (`schema.json`) with fields, relations, components, and dynamic zones

- Querying the REST API with filters, populate, sort, and pagination

- Creating custom controllers, services, routes, policies, or middlewares

- Using the Document Service API for back-end CRUD with draft/publish workflows

- Implementing JWT authentication with the Users & Permissions plugin

- Adding lifecycle hooks to content types for side effects

- Generating TypeScript types for content schemas

**Key patterns covered:**

- Content type schema definition (`schema.json`)

- REST API querying with `qs` (filters, populate, sort, pagination)

- Document Service API (`findMany`, `findOne`, `create`, `update`, `delete`, `publish`, `unpublish`)

- Custom controllers, services, routes, policies, and middlewares

- Lifecycle hooks (`beforeCreate`, `afterUpdate`, etc.)

- JWT authentication (register, login, authenticated requests)

- TypeScript type generation

**When NOT to use:**

- Direct database queries bypassing Strapi's API layer (use Strapi's Document Service)

- Complex transactional logic requiring raw SQL (Strapi abstracts the database)

**Detailed Resources:**

- For decision frameworks and quick-reference tables, see [reference.md](reference.md)

**Core & REST API:**

**Backend Customization:**

**Authentication:**

- [examples/auth.md](examples/auth.md) -- JWT authentication, registration, login, roles and permissions

---

<philosophy>

## Philosophy

Strapi is an open-source headless CMS built on Node.js (Koa) that auto-generates RESTful and GraphQL APIs from content type schemas. Content is defined via JSON schemas, managed through an admin panel, and consumed via generated API endpoints.

**Core principles:**

1. **Schema-driven content** -- Content types are defined in `schema.json` files that describe fields, relations, components, and dynamic zones. The admin panel Content-Type Builder provides a visual editor, but schemas are code that lives in your repository.

2. **Auto-generated APIs** -- Every content type automatically gets CRUD REST endpoints (`/api/:pluralApiId`) and optional GraphQL support. No manual route/controller creation needed for standard operations.

3. **Document Service API (v5)** -- The back-end API for accessing content from custom code, plugins, and lifecycle hooks. Replaces v4's Entity Service. Uses `documentId` (not database `id`) as the primary identifier.

4. **Draft & Publish** -- Content types can have draft/publish workflows. The Document Service defaults to `status: 'draft'`; published content requires `status: 'published'` or explicit `publish()` calls.

5. **Permission-first** -- All content type endpoints are private by default. Access must be explicitly granted via the admin panel (Users & Permissions plugin) or API tokens.

6. **Backend customization** -- Controllers, services, routes, policies, and middlewares can all be customized. Strapi follows an MVC-like pattern built on Koa.

</philosophy>

---

<patterns>

## Core Patterns

### Pattern 1: Content Type Schema

```json

{

"kind": "collectionType",

"info": {

"singularName": "article",

"pluralName": "articles",

},

"attributes": {

"author": {

"type": "relation",

"relation": "manyToOne",

"target": "api::author.author",

"inversedBy": "articles"

},

"blocks": {

"type": "dynamiczone",

}

}

}

```

---

### Pattern 2: REST API Querying with `qs`

```typescript

import qs from "qs";

const query = qs.stringify(

{

populate: {

categories: { fields: ["name", "slug"] },

},

},

{ encodeValuesOnly: true },

);

const { data, meta } = await response.json();

```

---

### Pattern 3: Document Service API (Back-End)

```typescript

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

const articles = await strapi.documents(CONTENT_TYPE_UID).findMany({

status: "published",

filters: { categories: { slug: { $eq: "news" } } },

populate: { author: true },

});

```

---

### Pattern 4: Custom Controllers

Extend or replace auto-generated controller actions. Controllers handle request/response logic and delegate to services. Use `createCoreController` from `factories` to inherit sanitization helpers.

```typescript

// src/api/article/controllers/article.ts

export default factories.createCoreController(

"api::article.article",

({ strapi }) => ({

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 });

},

}),

);

```

**Why good:** `validateQuery` + `sanitizeQuery` + `sanitizeOutput` enforce role-based field access, `transformResponse()` wraps output in `{ data, meta }` envelope

See [examples/backend.md](examples/backend.md) for full controller examples including custom actions (`findBySlug`, `incrementViews`, `search`).

---

### Pattern 5: Custom Routes

Define custom routes to expose custom controller actions. Custom route files sit alongside the core router.

```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 },

},

],

};

```

**Why good:** Separate file from core router, `handler` uses full UID, `auth: false` for public access, policies/middlewares attachable per-route

See [examples/backend.md](examples/backend.md) for route restriction with `only`, middleware attachment, and policy configuration.

---

### Pattern 6: Lifecycle Hooks

Register side effects on content type operations. Hooks are defined in `lifecycles.ts` files alongside the content type schema.

```typescript

// src/api/article/content-types/article/lifecycles.ts

export default {

async beforeCreate(event) {

/* event.params.data -- mutate to transform input */

},

async afterCreate(event) {

/* event.result -- the created document */

},

async beforeUpdate(event) {

/* event.params.data -- mutate before save */

},

async afterDelete(event) {

/* event.result -- cleanup related resources */

},

};

```

**Why good:** Hooks fire automatically on Document Service operations, `beforeXxx` can mutate `event.params.data`, `afterXxx` has `event.result`

See [examples/backend.md](examples/backend.md) for full lifecycle examples including slug generation, programmatic subscription, and audit logging.

---

### Pattern 7: Services

Services contain reusable business logic called by controllers. Use `createCoreService` to inherit default CRUD and add custom methods.

```typescript

export default factories.createCoreService(

"api::article.article",

({ strapi }) => ({

async findPublished(filters = {}) {

return strapi

.documents("api::article.article")

.findMany({ status: "published", filters });

},

}),

);

// Called via: strapi.service("api::article.article").findPublished()

```

**Why good:** Inherits default CRUD, custom methods encapsulate reusable query logic, called from controllers via `strapi.service(uid)`

See [examples/backend.md](examples/backend.md) for complex service examples including related-article queries and publish-with-notification patterns.

---

### Pattern 8: Policies

Policies are read-only functions that allow or deny access to a route. They return `true` (allow) or `false` (deny) and cannot modify the request.

```typescript

// src/api/article/policies/is-owner.ts

export default async (policyContext, config, { strapi }) => {

const article = await strapi.documents("api::article.article").findOne({

documentId: policyContext.params.documentId,

populate: { author: true },

});

return article?.author?.documentId === policyContext.state.user?.documentId;

};

```

**Why good:** Read-only check (no request mutation), applied per-action on core router config

See [examples/backend.md](examples/backend.md) for policy application to routes, rate limiting policies, and multi-policy chaining.

</patterns>

---

<decision_framework>

## Decision Framework

### REST API vs Document Service API

```

Where is your code running?

+-- Client-side (browser, frontend app)

| +-- Use REST API (fetch /api/:pluralApiId)

+-- Server-side (custom controller, service, plugin, lifecycle hook)

+-- Use Document Service API (strapi.documents(uid))

```

### Population Strategy

```

Do you need related data?

+-- NO --> Don't pass populate (leaner response)

+-- YES --> What level of control?

+-- All relations, 1 level --> populate: '*' (convenient but over-fetches)

+-- Specific relations --> populate: { relation: { fields: [...] } }

+-- Nested relations --> populate: { relation: { populate: { nested: true } } }

+-- Filtered relations --> populate: { relation: { filters: { ... } } }

```

### Content Type Kind

```

How many documents of this type exist?

+-- Many (articles, products, users) --> collectionType

+-- One (site settings, homepage, footer) --> singleType

```

### Custom Controller vs Default

```

Do default CRUD endpoints meet your needs?

+-- YES --> Use auto-generated routes (no custom controller needed)

+-- NO --> What do you need?

+-- Modified default behavior --> Override find/findOne/create/update/delete in createCoreController

+-- Entirely new endpoint --> Add custom action + custom route

+-- Access control logic --> Add a policy to the route config

+-- Request transformation --> Add a route middleware

```

### Draft & Publish

```

Does content need editorial review before going live?

+-- YES --> Enable draftAndPublish: true in schema

| +-- Document Service defaults to status: 'draft'

| +-- Use publish()/unpublish() to manage lifecycle

| +-- REST API returns published content by default

+-- NO --> Disable draftAndPublish (content is always live)

```

### Authentication Method

```

Who is consuming the API?

+-- End users (login/register) --> Users & Permissions plugin (JWT)

+-- External services/scripts --> API tokens (admin panel > Settings > API Tokens)

+-- Admin panel users --> Admin API tokens (separate from content API)

```

</decision_framework>

---

<red_flags>

## RED FLAGS

**High Priority Issues:**

- **Using `strapi.entityService` in v5** -- Entity Service is removed. Use `strapi.documents()` (Document Service API) for all back-end data access.

- **Not populating relations** -- Strapi returns NO relations, media, components, or dynamic zones by default. Forgetting `populate` results in null/missing fields that look like data loss.

- **Using `populate=*` in production** -- Fetches all relations one level deep, including data the user may not have permission to see. Use targeted population with field selection.

- **Manual query string construction** -- Building complex filter/populate URLs by hand breaks with special characters and nested params. Use the `qs` library.

- **Missing sanitization in custom controllers** -- Skipping `sanitizeQuery()`, `sanitizeOutput()`, and `validateQuery()` bypasses permission checks and exposes private fields.

**Medium Priority Issues:**

- **Confusing `documentId` with `id`** -- In v5, `documentId` is the persistent identifier across locales and draft/published versions. The database `id` is an internal integer. REST API and Document Service use `documentId`.

- **Not setting permissions** -- All content type endpoints are private by default. Without configuring permissions in the admin panel, API requests return 403.

- **Assuming default status is published** -- Document Service API defaults to `status: 'draft'`. You must explicitly pass `status: 'published'` to get published content.

- **Using `publicationState` parameter (v4 syntax)** -- Replaced in v5 by `status` parameter and dedicated `publish()`/`unpublish()` methods.

- **Forgetting `encodeValuesOnly: true` in `qs.stringify`** -- Without this option, `qs` encodes array bracket indices, which Strapi's parser may not handle correctly.

**Common Mistakes:**

- **Not awaiting `.commit()` equivalent** -- Document Service methods return promises. Always `await` them.

- **Missing `_type` or `_key` in components** -- Dynamic zone and component fields need `__component` identifiers when creating/updating via the API.

- **Hardcoded Strapi URL** -- Use environment variables (`STRAPI_URL`) for the API base URL; hardcoded `localhost:1337` breaks in production.

- **Mixing pagination methods** -- Use either `page`/`pageSize` OR `start`/`limit`, never both in the same query.

**Gotchas & Edge Cases:**

- **v5 response format is flat** -- v4 nested data in `data.attributes`; v5 puts fields directly on the data object. Existing frontend code from v4 will break.

- **Bulk lifecycle hooks never fire from Document Service** -- `beforeCreateMany`, `afterDeleteMany`, etc. are database-level hooks. Document Service operations trigger single-document hooks only.

- **Dynamic zone `populate` uses `on` syntax** -- To populate specific components in a dynamic zone, use `populate: { blocks: { on: { 'blocks.hero': { populate: '*' } } } }`.

- **Media fields are relations internally** -- Media uploads are stored in the `upload` plugin and referenced via relations. They follow the same populate rules as other relations.

- **Draft changes are invisible to REST API by default** -- The REST API returns published content. To see drafts, you need a token with appropriate permissions and the `status=draft` parameter.

</red_flags>

---

<critical_reminders>

## CRITICAL REMINDERS

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `strapi.documents('api::content-type.content-type')` (Document Service API) for all back-end data access in Strapi v5 -- the Entity Service API is removed)**

**(You MUST always pass `populate` when you need relations, media, components, or dynamic zones -- Strapi returns NO relations by default)**

**(You MUST use the `qs` library to build complex REST API query strings with filters, populate, and sort -- manual string construction breaks with nested params)**

**(You MUST sanitize and validate both input and output in custom controllers using `this.sanitizeQuery(ctx)`, `this.sanitizeOutput()`, and `this.validateQuery(ctx)`)**

**(You MUST set permissions for every content type endpoint via the admin panel or config -- all routes are private by default)**

**Failure to follow these rules will cause missing data (no populate), security vulnerabilities (no sanitization), broken queries (no qs), and 403 errors (no permissions).**

</critical_reminders>