Checkpoint API Route

Before proceeding, test your understanding:

1. Why do we execute workflows from API routes instead of calling services directly?

   Workflows provide orchestration, rollback, and transaction management. If you call services directly from routes, you have to manually handle rollback logic when errors occur. Workflows handle this automatically through compensation functions. This becomes crucial as your business logic grows more complex with multiple steps.

2. What does validateAndTransformBody middleware do?

   It validates incoming request body against a Zod schema BEFORE your route handler runs. If validation fails, it automatically returns a 400 error with validation details. If validation succeeds, it transforms the data according to the schema and passes the validated data to your handler. This ensures your handler only receives valid data.

3. Why do we use MedusaRequest and MedusaResponse instead of Express types?

   These are Medusa-specific types that extend Express types with additional properties like scope (for dependency injection) and queryConfig (for filtering/pagination). Using these types gives you type-safe access to Medusa-specific features.

4. What is the scope object and how does it work?

   scope is Medusa’s dependency injection container scoped to the current request. You pass it to workflows when executing them (e.g., workflow(req.scope).run()), and use it to resolve services (e.g., scope.resolve("query")). Each request gets its own scope, ensuring proper isolation and allowing request-specific configuration.

Implementation Check

Let me verify your implementation. Please share the following:

1. Schema File

Show me your src/api/admin/brands/validators.ts file.

Key things to check:

• Not done: Imports z from “@medusajs/framework/zod”
• Not done: Defines CreateBrandSchema with z.object()
• Not done: Has name field with z.string()
• Not done: Exports schema as named export

2. Route File

Show me your src/api/admin/brands/route.ts file.

Key things to check:

• Not done: Imports types: MedusaRequest, MedusaResponse
• Not done: Imports workflow: import { createBrandWorkflow } from "..."
• Not done: Imports workflow input type: CreateBrandWorkflowInput
• Not done: Defines POST function (must be named POST exactly)
• Not done: Uses type: MedusaRequest<CreateBrandWorkflowInput>
• Not done: Executes workflow: await createBrandWorkflow(req.scope).run({ input: ... })
• Not done: Extracts brand from result: result.result or result.brand
• Not done: Returns JSON: res.json({ brand })
• Not done: Handles errors with try/catch

3. Middleware File

Show me your src/api/middlewares.ts file.

Key things to check:

• Not done: Imports defineMiddlewares, validateAndTransformBody
• Not done: Imports CreateBrandSchema
• Not done: Exports default defineMiddlewares()
• Not done: Has routes array
• Not done: Route config has matcher: "/admin/brands"
• Not done: Route config has method: "POST"
• Not done: Route config has middlewares array with validateAndTransformBody()

4. Server Running

Start your dev server:

Expected output: Server should start without errors. Check that there are no errors about missing routes or middleware.

Common Issues

Middleware not running / validation not working

Symptom: Invalid data passes through without validation errors

Cause: Middleware not configured correctly

Fix:

1. Check that matcher exactly matches your route: "/admin/brands"
2. Check that method is uppercase: "POST"
3. Ensure middlewares.ts is in the correct location: src/api/middlewares.ts
4. Restart dev server after middleware changes

“Empty array returned” or “brand is undefined”

Symptom: API returns empty response or undefined brand

Cause: Not extracting brand from workflow result correctly

Fix: Workflow results are nested:

The first .result is the workflow execution result, the second .result is from WorkflowResponse(brand).

Route not found / 404 error

Symptom: cURL returns 404

Cause: File not in correct location or not named correctly

Fix:

1. Ensure file is at: src/api/admin/brands/route.ts
2. Ensure function is exported as POST (not default export)
3. Restart dev server
4. Check URL is correct: http://localhost:9000/admin/brands

“Workflow failed” with no specific error

Symptom: Generic workflow failure

Cause: Error in step execution (likely in createBrandStep)

Fix:

1. Check server logs for detailed error message
2. Verify brand service is accessible in the step
3. Verify database connection is working
4. Check that migrations ran successfully

TypeScript error: “Property ‘validatedBody’ does not exist”

Symptom: Build fails with TS error

Cause: Missing type for validated body

Fix: Use generic type parameter:

Testing Checklist

Verify each of these steps:

• Not done: Server starts without errors
• Not done: POST request to /admin/brands succeeds
• Not done: Response contains brand object with id and name
• Not done: Invalid request (missing name) returns 400 error
• Not done: Brand is actually saved (check with GET request or database query)
• Not done: Build succeeds: npm run build

Manual Database Verification (Optional)

If you want to verify the brand was actually saved:

You should see the Nike brand you created.

Architecture Understanding

At this point, you should understand the full three-layer pattern:

Why this matters:

• Separation of concerns: Each layer has a single responsibility
• Reusability: Workflow can be called from multiple routes (HTTP, GraphQL, CLI)
• Testability: Each layer can be tested independently
• Maintainability: Changes to one layer don’t affect others

Next Steps

Once this checkpoint passes:

1. Lesson 1 Complete! You’ve built a complete feature from scratch:

   • Brand Module (data layer)
   • createBrandWorkflow (business logic with rollback)
   • POST /admin/brands (HTTP interface with validation)

2. Commit your work:

   bashCopy

   git add .
   git commit -m "Complete Lesson 1: Build custom brand feature"

3. Next: Lesson 2 - Extend Medusa

   • Link brands to products using Module Links
   • Extend core workflows using Workflow Hooks
   • Query linked data across modules

Ready for Lesson 2? This is where it gets really interesting - you’ll learn how to extend Medusa’s core functionality without forking the codebase.