Endpoint Development

Development Workflow

1. Write integration tests first (in [module].api.test.ts)
2. See them fail (red): make test-server-file GREP="ModuleName"
3. Implement the endpoint (controller + routing)
4. See them pass (green): make test-server-file GREP="ModuleName"
5. Add/update documentation:
   • [module].api.docs.yaml — OpenAPI spec
   • Tag in server/src/docs/index.ts (if adding tags)
6. Verify: make build-server, then confirm endpoints appear in http://localhost:10020/swagger.json
7. Final check: make prettier-server && make lint-server && make build-server && make test-server

Reference Implementation

Study server/src/api/healthCheck/ before creating a new endpoint. It shows the exact file structure, controller pattern, test pattern, and OpenAPI docs format used in this project.

Integration Testing

Philosophy

These are integration tests that test all functionality through the full stack. Test real behavior without mocking anything internally.

Mocking Rules

Only mock at borders — calls to outside services:

• External APIs (Spotify, AWS S3, etc.)
• Email services
• Push notification services
• Third-party webhooks

Never mock internal services, database calls, or library functions.

Use nock for HTTP mocking (already set up in mochaSetup.test.ts).

Test Data Generation

Always use server/src/test/testDataGenerator.ts for generating test models:

typescript
1import { createUser } from "../../test/testDataGenerator";

DO NOT manually create users with hardcoded emails:

typescript
1// BAD - can cause duplicate email conflicts between tests
2const adminUser = await db.models.User.create({
3  email: "admin@example.com",
4  role: "admin",
5});
6
7// GOOD - let testDataGenerator handle unique emails
8const adminUser = await createUser(db, { role: "admin" });

Generating Tokens

typescript
1import { generateToken } from "../../utils/jwt";
2
3const user = await createUser(db);
4const token = await generateToken(user);

If generateToken doesn't exist yet, create a JWT token directly using the user's jwtRepr() method and the JWT_SECRET from config.

Test File Location

server/src/api/[module]/[module].api.test.ts (co-located with controller)

Test Pattern

typescript
1import { assert } from "chai";
2import request from "supertest";
3import app from "../../server";
4import db from "../../db";
5import { createUser } from "../../test/testDataGenerator";
6
7describe("[Module] API", function () {
8  describe("GET /v1/[module]", function () {
9    it("returns the resource", async function () {
10      const user = await createUser(db, { role: "admin" });
11      // generate token for auth...
12
13      const res = await request(app)
14        .get("/v1/[module]")
15        .set("Authorization", `Bearer ${token}`)
16        .expect(200);
17
18      assert.exists(res.body.id);
19    });
20
21    it("returns 401 without auth", async function () {
22      await request(app).get("/v1/[module]").expect(401);
23    });
24  });
25});

REST Conventions

URL Structure

• All endpoints prefixed with /v1/
• Routes mounted in server/src/api/routes.ts
• Use kebab-case: /audio-blocks, not /audioBlocks
• Use plural nouns: /users, /stations
• Use lowercase

The /:userId/ Pattern with me

User-related endpoints use /:userId/ where me resolves to the authenticated user's ID via the isOperatingOnSelf middleware.

GET  /v1/users/me           → Get current user
GET  /v1/users/:userId      → Get specific user (admin)

HTTP Methods & Status Codes

Authentication & Authorization Middleware Stack

Apply middleware in this order on protected routes:

typescript
1router.get(
2  "/:id",
3  authenticate,                           // 1. Validate JWT
4  validateUUIDsInParams(["id"]),          // 2. Validate UUID format
5  requireRoleOfAtLeast("user"),           // 3. Check permissions
6  controller.get,                          // 4. Handler
7);
8
9router.post(
10  "/",
11  authenticate,
12  checkBodyFor(["name", "email"]),         // Required fields
13  checkBodyForNoExtraFields(["name", "email", "role"]),  // No extra fields
14  validateUUIDsInBody(["relatedId"]),     // UUID format in body
15  controller.create,
16);

Permission Middleware Options:

typescript
1requireRoleOfAtLeast("admin")         // Roles: guest < user < admin
2isOperatingOnSelf("userId")           // User can only operate on own data
3oneOf([                               // OR logic
4  isOperatingOnSelf("userId"),
5  requireRoleOfAtLeast("admin"),
6])

Error Handling

Error Classes (in utils/errors.ts):

• NotFoundError → 404
• AuthenticationError → 401
• PermissionError → 403
• ValidationError → 400
• ConflictError → 409

typescript
1// Use centralized error messages
2throw new NotFoundError(ErrorMessages.RESOURCE_NOT_FOUND);
3throw new ValidationError(ErrorMessages.invalidUuidFormat("userId"));

Controller pattern:

typescript
1async function handler(req: Request, res: Response, next: NextFunction) {
2  try {
3    // ... implementation
4    res.status(200).json(result);
5  } catch (error) {
6    next(error);
7  }
8}

Response Structure

Single resource: { "id": "uuid", "name": "value", ... }

Collection: [{ "id": "uuid1", ... }, { "id": "uuid2", ... }]

Error: { "error": { "message": "Error description" } }

File Organization

server/src/api/
├── routes.ts                     # Main route mounting
├── security.ts                   # Auth middleware
├── validation.ts                 # Validation middleware
├── [module]/
│   ├── index.ts                  # Route definitions (Express Router)
│   ├── [module].api.ts           # Controller (handler functions)
│   ├── [module].api.test.ts      # Integration tests
│   └── [module].api.docs.yaml    # OpenAPI documentation

API Documentation

Creating Docs

1. [module].api.docs.yaml — OpenAPI 3.0 spec. See healthCheck/healthCheck.api.docs.yaml for reference.
2. Tag registration — Add the module's tag to the tags array in server/src/docs/index.ts if you're using tags.
3. The YAML files are auto-discovered by the glob pattern in docs/index.ts.

Verification

bash
1make build-server
2# Then check: http://localhost:10020/swagger.json

Route Registration

In server/src/api/routes.ts, add the new route:

typescript
1import moduleApi from "./[module]";
2
3function addRoutes(app: Application) {
4  // ... existing routes
5  app.use("/v1/[module]", moduleApi);
6}

Anti-Patterns to Avoid

DON'T: Handle errors with res.status().json() — throw typed errors instead.

DON'T: Use /mine or implicit user endpoints — use /:userId/ with me support.

DON'T: Mock internal services — only mock at external boundaries.

Quality Gates

• Integration tests written and passing
• Controller follows try-catch-next pattern
• Proper error classes used (not raw status codes)
• Route registered in routes.ts
• OpenAPI docs in .api.docs.yaml
• make prettier-server passes
• make lint-server passes
• make build-server passes
• make test-server passes