The hub skill for all API/backend architecture in Webiny. Covers architecture overview, Services vs UseCases, feature naming and organization, feature structure templates, DI decision tree, anti-patterns, createFeature, createAbstraction, container registration, domain errors, entity and value object patterns, naming conventions, scoping rules, and code conventions. Use this skill for ANY backend API work — it references sub-skills for deep implementation details.
79%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./skills/user-skills/api/api-architect/SKILL.mdAPI extensions use createFeature to register features into the DI container. Each feature is a vertical slice with abstractions, implementations, and a feature.ts registration file. The key abstractions are Services (multi-method, singleton) and UseCases (single-method orchestrators, transient). Repositories handle persistence via CMS. Features are named by business capability, files inside by technical responsibility.
This skill applies to both extension developers (working in extensions/) and core developers (working in packages/). The architecture patterns are identical — only imports and registration differ.
Extensions (extensions/) | Core (packages/) | |
|---|---|---|
| Imports | webiny/api, webiny/api/cms/model, etc. | @webiny/feature/api, @webiny/api-headless-cms/..., etc. |
| Catalog paths | Use the Import: path | Use the Source: path |
| Entry point | export default createFeature(...) in a file targeted by <Api.Extension src={...}> | createFeature registered by the package initializer |
| GraphQL schemas | export default GraphQLSchemaFactory.createImplementation(...) — registered via container.register() inside the entry point's createFeature | Same pattern, but imported from @webiny/handler-graphql |
Detect which context you're in by checking the file path: extensions/ → extension mode, packages/ → core mode.
Extension (root) ── registers ──> Features + GraphQL Schemas + Models
Feature ── registers ──> UseCase | Service | EventHandler + Repository
UseCase ── depends on ──> Service | Repository (+ EventPublisher)
Repository ── depends on ──> CMS Use Cases (GetModel, CreateEntry, etc.)
Service ── depends on ──> external APIs, other Servicesexecute()). Coordinates services, repositories, and events. Transient scope.Multi-method abstractions for external API calls or cohesive domain logic. A service groups related operations that belong together.
// abstractions.ts
export interface ILingotekService {
translate(documentId: string, targetLocale: string): Promise<Result<void, Error>>;
getTranslationStatus(documentId: string): Promise<Result<TranslationStatus, Error>>;
deleteProject(projectId: string): Promise<Result<void, Error>>;
}
export const LingotekService = createAbstraction<ILingotekService>("MyExt/LingotekService");
export namespace LingotekService {
export type Interface = ILingotekService;
}.inSingletonScope())features/{serviceName}/ or features/services/{serviceName}/async getService() that lazily initializes and caches the service. Consumers inject the provider, not the service directly. See the ServiceProvider section below.Single-method orchestrators with an execute() method. They coordinate services, repositories, and events.
export interface ISyncProjectUseCase {
execute(input: SyncProjectInput): Promise<Result<Project, SyncProjectError>>;
}features/{ActionEntity}/When a service requires async initialization (loading CMS settings, fetching remote config, API tokens), use a ServiceProvider — a provider abstraction with async getService() that lazily creates and caches the service. Both the provider and the service are part of the same feature. The provider is the primary abstraction exported from the feature. The service itself is not registered in the DI container.
// abstractions.ts
export interface ILingotekServiceProvider {
getService(): Promise<ILingotekService>;
}
export const LingotekServiceProvider = createAbstraction<ILingotekServiceProvider>(
"MyExt/LingotekServiceProvider"
);
export namespace LingotekServiceProvider {
export type Interface = ILingotekServiceProvider;
}// LingotekServiceProvider.ts
class LingotekServiceProviderImpl implements ProviderAbstraction.Interface {
private service: ILingotekService | undefined;
constructor(private getSettings: GetSettingsUseCase.Interface) {}
async getService(): Promise<ILingotekService> {
if (!this.service) {
const result = await this.getSettings.execute();
const settings = result.isOk() ? result.value : defaultSettings;
this.service = new LingotekService(settings);
}
return this.service;
}
}await provider.getService() before using the serviceLingotekServiceProvider, not LingotekServiceFeatures use a two-level naming convention:
This makes features discoverable by what they DO, and once inside a feature folder, you see the technical components clearly.
features/
├── syncToLingotek/ ← business capability
│ ├── abstractions.ts
│ ├── SyncProjectUseCase.ts ← technical responsibility
│ ├── EntryAfterCreateHandler.ts ← technical responsibility (fine as filename!)
│ ├── EntryAfterUpdateHandler.ts
│ └── feature.ts
├── cleanupLingotekDocument/
│ ├── EntryBeforeDeleteHandler.ts
│ └── feature.tsfeatures/
├── EntryAfterCreateHandler/ ← ❌ technical name as feature directory
├── DocumentBeforeDeleteHandler/ ← ❌ technical name as feature directorysyncToLingotek, cleanupOnDelete, notifySlackEntryAfterCreateHandler.ts, SyncProjectUseCase.tsfeatures/, never in a separate handlers/ directoryWhen: handler calls a service or use case, no new abstractions needed.
features/cleanupOnDelete/
├── CleanupOnDeleteHandler.ts # Implements an existing EventHandler abstraction
└── feature.ts # Registers the handlerWhen: logic is reused by GraphQL + event handlers, or coordinates multiple services.
features/syncProjectToLingotek/
├── abstractions.ts # UseCase + error types for this feature
├── CreateProjectUseCase.ts
├── UpdateProjectUseCase.ts
├── DeleteProjectUseCase.ts
├── EntryAfterCreateHandler.ts # Thin handler → delegates to CreateProjectUseCase
├── EntryAfterUpdateHandler.ts # Thin handler → delegates to UpdateProjectUseCase
├── EntryAfterDeleteHandler.ts # Thin handler → delegates to DeleteProjectUseCase
└── feature.ts # Registers everythingWhen: reusable multi-method service for an external API or domain area.
features/lingotekService/
├── abstractions.ts # Service interface (multi-method)
├── LingotekService.ts # Implementation
└── feature.ts # Registers in singleton scope| You're building a... | It needs to... | Inject |
|---|---|---|
| Event Handler | Call external API | Service |
| Event Handler | Orchestrate CMS + external | UseCase |
| Event Handler | Just log/validate | Logger (or nothing) |
| GraphQL Resolver | Simple read | Service or Repository directly |
| GraphQL Resolver | Complex mutation | UseCase |
| GraphQL Resolver | Check permissions | IdentityContext or Permissions abstraction |
| UseCase | Call external API | Service |
| UseCase | Persist/read data | Repository |
| UseCase | Publish domain events | EventPublisher |
| UseCase | Check permissions | IdentityContext or Permissions abstraction |
| Repository | Access CMS | GetModelUseCase, CreateEntryUseCase, etc. |
// WRONG — separate abstractions for related operations
export const DeleteDocumentService = createAbstraction(...)
export const CreateDocumentService = createAbstraction(...)
export const UpdateDocumentService = createAbstraction(...)
// CORRECT — one multi-method Service
export interface IDocumentService {
create(input: CreateInput): Promise<Result<Doc, Error>>;
update(id: string, input: UpdateInput): Promise<Result<Doc, Error>>;
delete(id: string): Promise<Result<void, Error>>;
}
export const DocumentService = createAbstraction<IDocumentService>("MyExt/DocumentService");features/DocumentBeforeDeleteHandler/ ← WRONG: technical name
features/cleanupLingotekDocument/ ← CORRECT: business capability// WRONG — no builder pattern exists
builder.role({ ... }).permissions([...])
// CORRECT — factories return plain objects
async execute(): Promise<CodeRole[]> {
return [{ name: "Admin", slug: "admin", description: "...", permissions: [...] }];
}api/handlers/MyHandler.ts ← WRONG: handlers are features
features/myFeature/MyHandler.ts ← CORRECT: handler lives inside its feature// WRONG
throw new Error("Not found");
// CORRECT
return Result.fail(new EntityNotFoundError(id));// WRONG — the rules of one domain value scattered across helper functions and call sites
// domain/globalComponentEntryId.ts
export const createGlobalComponentEntryId = (name: string, language: string) => `wbgc-${hash(name, language)}`;
// utils/language.ts
export const normalizeLanguage = (language?: string | null) => language || "default";
export const isDefaultLanguage = (language?: string | null) => !language || language === "default";
// SomeUseCase.ts
const language = input.language || "default"; // the rule, copied again
// CORRECT — one value object owns the value and its rules
const language = GlobalComponentLanguage.from(input.language);
const entryId = GlobalComponentEntryId.from(input.name, language.toString());
if (language.isDefault()) { ... }See Value Objects for Domain Values.
// WRONG — fires for ALL models
async handle(event) {
await this.service.doWork(event.payload.entry);
}
// CORRECT — filter by your model
async handle(event) {
if (event.payload.model.modelId !== MY_MODEL_ID) return;
await this.service.doWork(event.payload.entry);
}api/
├── Extension.ts # API entry point (createFeature, registers everything)
├── domain/
│ ├── errors.ts # Domain-specific errors (extend BaseError)
│ ├── EntityId.ts # Value object for entity IDs (one file per value object)
│ ├── EntityLanguage.ts # Value object for any other domain value with rules
│ ├── EntityModel.ts # CMS model definition (ModelFactory)
│ └── EntityModelExtension.ts # Abstraction for extending the model
├── features/
│ ├── createEntity/ # Feature: business capability
│ │ ├── abstractions.ts # UseCase + Repository abstractions + error types
│ │ ├── feature.ts # DI registration
│ │ ├── CreateEntityUseCase.ts
│ │ └── CreateEntityRepository.ts
│ ├── lingotekService/ # Service feature
│ │ ├── abstractions.ts
│ │ ├── LingotekService.ts
│ │ └── feature.ts
│ └── syncToLingotek/ # Event handler feature
│ ├── EntryAfterCreateHandler.ts
│ └── feature.ts
└── graphql/
├── CreateEntitySchema.ts
└── GetEntitySchema.ts// src/api/Extension.ts
import { createFeature } from "webiny/api";
import EntityModel from "./domain/EntityModel.js";
import CreateEntitySchema from "./graphql/CreateEntitySchema.js";
import { CreateEntityFeature } from "./features/createEntity/feature.js";
import { LingotekServiceFeature } from "./features/lingotekService/feature.js";
import { SyncToLingotekFeature } from "./features/syncToLingotek/feature.js";
export const Extension = createFeature({
name: "MyExtension",
register(container) {
// CMS model (register first)
container.register(EntityModel);
// GraphQL schemas
container.register(CreateEntitySchema);
// Features (use Feature.register, NOT container.register)
CreateEntityFeature.register(container);
LingotekServiceFeature.register(container);
SyncToLingotekFeature.register(container);
}
});Rules:
container.register().Feature.register(container) (not container.register(Feature)).Every piece of business logic starts with a typed abstraction token:
// src/api/features/createEntity/abstractions.ts
import { createAbstraction, Result } from "webiny/api";
import type { MyEntity } from "~/shared/MyEntity.js";
export interface ICreateEntityInput {
name: string;
}
export interface ICreateEntityUseCase {
execute(input: ICreateEntityInput): Promise<Result<MyEntity, Error>>;
}
export const CreateEntityUseCase = createAbstraction<ICreateEntityUseCase>(
"MyExtension/CreateEntityUseCase"
);
// Namespace re-exports all related types for convenient access
export namespace CreateEntityUseCase {
export type Interface = ICreateEntityUseCase;
export type Input = ICreateEntityInput;
}// src/api/features/createEntity/feature.ts
import { createFeature } from "webiny/api";
import CreateEntityUseCase from "./CreateEntityUseCase.js";
import CreateEntityRepository from "./CreateEntityRepository.js";
export const CreateEntityFeature = createFeature({
name: "CreateEntity",
register(container) {
container.register(CreateEntityUseCase); // transient (default)
container.register(CreateEntityRepository).inSingletonScope(); // singleton
}
});| Method | When to Use |
|---|---|
container.register(Implementation) | Register a class (created via Abstraction.createImplementation) |
container.registerInstance(abstraction, instance) | Register a plain object that satisfies the interface |
container.registerFactory(abstraction, () => instance) | Register a lazy factory |
container.registerDecorator(Decorator) | Register a decorator (wraps existing implementation) |
A deployed API must NEVER use process.env to read configuration. All configuration flows through BuildParams via DI:
import { BuildParams } from "webiny/api";
class MyServiceImpl implements MyService.Interface {
constructor(private buildParams: BuildParams.Interface) {}
doSomething() {
// buildParams.get() returns T | null — always handle null
const endpoint = this.buildParams.get<string>("MY_API_ENDPOINT");
if (!endpoint) {
throw new Error("MY_API_ENDPOINT build param is not configured.");
}
}
}
export default MyService.createImplementation({
implementation: MyServiceImpl,
dependencies: [BuildParams]
});Note: BuildParam declarations (
<Api.BuildParam>) live in the top-level extension component — see the webiny-full-stack-architect skill.
Every feature defines domain-specific errors extending BaseError:
// domain/errors.ts
import { BaseError } from "webiny/api";
export class EntityNotFoundError extends BaseError {
override readonly code = "Entity/NotFound" as const;
constructor(id: string) {
super({ message: `Entity with id "${id}" was not found!` });
}
}
export class EntityPersistenceError extends BaseError<{ error: Error }> {
override readonly code = "Entity/Persist" as const;
constructor(error: Error) {
super({ message: error.message, data: { error } });
}
}Rules:
BaseError from webiny/apioverride readonly code with a namespaced string ("Domain/ErrorType")as const on the code for type narrowingdata, define a type and pass it as generic: BaseError<TDataType>Define error interfaces and union types so consumers know exactly which errors can occur:
// features/createEntity/abstractions.ts
export interface ICreateEntityErrors {
persistence: EntityPersistenceError;
notFound: EntityModelNotFoundError;
notAuthorized: NotAuthorizedError;
}
type CreateEntityError = ICreateEntityErrors[keyof ICreateEntityErrors];
export interface ICreateEntityUseCase {
execute(input: CreateEntityInput): Promise<Result<Entity, CreateEntityError>>;
}
export namespace CreateEntityUseCase {
export type Interface = ICreateEntityUseCase;
export type Input = CreateEntityInput;
export type Error = CreateEntityError;
export type Return = Promise<Result<Entity, CreateEntityError>>;
}Error and Return types in the namespace for consumersRULE: any domain value that has rules — how it's derived, normalised, defaulted, validated or compared — is a value object: a class in domain/, named after the domain concept. Never a loose helper function (createXyzId(), normalizeXyz(), isDefaultXyz()), a utils/ module, or a rule repeated inline at call sites (language || "default").
Typical domain values: entry ids derived from other values, language codes with a fallback, keys and slugs, paths, names with format rules, documents with invariants (e.g. "exactly one main content element").
A plain string with no rules (a title, a description) stays a string — don't wrap it.
Shape:
from(...) for input, fromStored(...) when stored data needs different handling (legacy shapes, missing values), create() / createDefault() for new values.static readonly members, not module-level magic strings.isDefault(), equals(other), matches(raw). Callers never compare raw values themselves.toString() (or readonly fields for compound values) to hand the raw value to persistence, GraphQL and events.withX(...)).EntryId) are fine.// domain/EntityLanguage.ts
/**
* The language an entity is stored in: the language code it was created in, or `"default"` without one.
*/
export class EntityLanguage {
static readonly DEFAULT = "default";
private constructor(private readonly code: string) {}
static from(language: unknown): EntityLanguage {
return typeof language === "string" && language.length > 0
? new EntityLanguage(language)
: new EntityLanguage(EntityLanguage.DEFAULT);
}
isDefault(): boolean {
return this.code === EntityLanguage.DEFAULT;
}
equals(other: EntityLanguage): boolean {
return other.code === this.code;
}
toString(): string {
return this.code;
}
}Where they're used:
toString() only at the edge: the repository's storage call, a GraphQL response, an event payload.Input (so external callers and replaced repositories stay simple), but the use case converts them to value objects before doing anything with them.validate() or isValid()); the use case turns a failure into a domain error and returns Result.fail(...).shared/ (see webiny-full-stack-architect) — never two copies of the rule.// domain/EntityId.ts
import { EntryId } from "webiny/api/cms/entry";
export class EntityId {
private constructor(private readonly id: string) {}
static create(): EntityId {
return new EntityId(EntryId.create().id);
}
static from(id: string): EntityId {
return new EntityId(EntryId.from(id).id); // Ensure clean id without revision suffix
}
equals(other: EntityId): boolean {
return other.id === this.id;
}
toString(): string {
return this.id;
}
}An id derived from other values (so the same inputs always give the same entry, and two concurrent first saves can't create two records) is a value object too:
// domain/EntitySettingsEntryId.ts
// Core packages use `createCacheKey` from `@webiny/utils` (as `ScheduledActionId` in api-scheduler does).
// Extensions don't have it: hash with `createHash` from `node:crypto` instead.
import { createCacheKey } from "@webiny/utils";
export class EntitySettingsEntryId {
private constructor(private readonly id: string) {}
static from(name: string, language: EntityLanguage): EntitySettingsEntryId {
return new EntitySettingsEntryId(
`settings-${createCacheKey([name, language.toString()]).slice(-24)}`
);
}
toString(): string {
return this.id;
}
}// shared/Entity.ts
export interface EntityDto {
id: string;
values: EntityValues;
}
export class Entity {
private constructor(private dto: EntityDto) {}
static from(dto: EntityDto) {
return new Entity(dto);
}
get id() {
return this.dto.id;
}
get values() {
return this.dto.values;
}
}index.ts)Each feature folder exports only abstractions — never features, events, or implementations:
// features/disableEntity/index.ts
export {
DisableEntityUseCase,
EntityBeforeDisableEventHandler,
EntityAfterDisableEventHandler
} from "./abstractions.js";Rules:
export { } syntax, NOT export *feature.ts, events.ts, or implementation files| Layer | Scope | Rationale |
|---|---|---|
| UseCase | Transient (default) | Fresh per invocation |
| Service | .inSingletonScope() | Stateful or expensive to create |
| Repository | .inSingletonScope() | One cache instance |
| Gateway | .inSingletonScope() | Stateless but expensive to create |
| EventHandler | Transient (default) | Fresh per event |
| CMS Model | Register normally | Registered once at boot |
| GraphQL Schema | Register normally | Registered once at boot |
| Artifact | Pattern | Example |
|---|---|---|
| Feature dir | {businessCapability} (camelCase) | syncToLingotek, createEntity |
| UseCase | {Action}{Entity}UseCase | CreateTenantUseCase |
| Service | {Domain}Service | LingotekService |
| Repository | {Action}{Entity}Repository | CreateTenantRepository |
| Event | {Entity}{Before|After}{Action}Event | TenantBeforeDisableEvent |
| Handler | {Entity}{Before|After}{Action}EventHandler | TenantBeforeDisableEventHandler |
| Decorator | {Action}{Entity}With{Concern} | GetEntityByIdWithAuthorization |
| Mapper | EntryTo{Entity}Mapper | EntryToFolderMapper |
| Error | {Entity}{Problem}Error | EntityNotFoundError |
| Value object | {Entity}{Concept} in domain/{Name}.ts | GlobalComponentLanguage |
createAbstraction from webiny/api — never new Abstraction()createImplementation with a dependencies array matching constructor ordercreateImplementation result (as default).js extensions in all relative imports (ESM)~ alias for package-internal absolute importsResult<T, E>. Check result.isFail() before result.valuenull — use domain-specific NotFoundErrordomain/ — never helper functions or inline rulesWhen building a new API feature:
BaseError with override readonly codedomain/, with no helper functions or utils/ modules for itInterface + Error.Interface, uses createImplementation.Interface, uses CMS use cases, wraps errorscontainer.registerDecorator(), decoratee is last constructor paramGraphQLSchemaFactory.InterfaceInterface + Event namespaceindex.ts exports abstractions only — no features, no event classes, no implementations.js extensioncreateAbstraction<T>(name: string)Creates a typed DI token. The generic T is the interface that implementations must satisfy.
| Import | import { createAbstraction } from "webiny/api" |
|---|---|
| Returns | Abstraction<T> |
createFeature(def)Creates a feature definition that the framework loads as an extension.
| Import | import { createFeature } from "webiny/api" |
|---|---|
def.name | Unique feature name (convention: "AppName/FeatureName") |
def.register(container) | Called at startup with the DI Container instance |
createAbstraction + createFeature. Never put logic directly in an EventHandler, GraphQL resolver, or CLI command.namespace MyAbstraction { export type Interface = ...; } so consumers can type dependencies as MyAbstraction.Interface."AppName/FeatureName" convention.dependencies array must match constructor parameter order exactly.process.env at runtime — deployed API services must NEVER read process.env. All configuration flows through BuildParams..inSingletonScope())..js extensions in import paths (ESM).domain/; its rules live only there.Api.Route and HttpRouteHandler.InterfacecreateImplementation DI pattern and injectable serviceswebiny/webiny-js
3cb652c
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.