What is the Mock API (in simple words)?

The Mock API is an HTTP interceptor for Angular that can answer requests right inside the app, without contacting a real server. It lets us develop screens quickly with predictable data.

• It is not a database and does not persist on a backend.
• It can simulate latency, headers, and errors.
• If a request is not mocked and fallbackToNetwork: true is enabled, the request continues to the real server.

How it’s enabled in docs-angular

En app.config.ts la app registra el interceptor y lo configura en el arranque (solo en dev):

provideHttpClient(
  withInterceptorsFromDi(),
  withInterceptors([mockHttpInterceptor])
),

// In APP_INITIALIZER
utils.configureMockInterceptor(
  {
    enabled: !environment.production,
    fallbackToNetwork: true,
    delay: [80, 220],
    logging: { enabled: true, level: 'info', logRequests: true },
  },
  DocsMocks
);

Mocks are defined in apps/docs-angular/src/app/mocks/index.ts:

export const DocsMocks: MockDefinition = {
  'GET /api/docs/health': () => ({ status: 200, data: { ok: true } }),
  'GET /api/docs/projects': () => ({ status: 200, data: [ { id: 'public', name: 'Public Docs' } ] }),
};

Each entry follows: 'VERB /path' : (req) => MockResponse.

Does it actually save data?

• If you call a mocked route (e.g., POST /api/users) and your mock returns 201, that “creation” only happens in memory. Nothing is written to a real server.
• You can enable client‑side caching (IndexedDB/LocalStorage/memory) for responses, but that’s still on the client.
• For real persistence (e.g., editor configuration), we use real endpoints. In this repo, saving docs-folders-config.json goes through POST /api/admin/docs/save-folders-config (served by the proxy on 5011). That route is not mocked, so you see matched: false and the server writes the file.

Recommended usage pattern

1. Define mocks para flujos de lectura/escritura que no dependan de persistencia real.
2. Para persistencia real, usa un endpoint del servidor (no lo moquees) y deja fallbackToNetwork: true.
3. Aprovecha latencias simuladas y logging para probar UX.

Complete example (docs-angular)

// apps/docs-angular/src/app/mocks/index.ts
export const DocsMocks: MockDefinition = {
  'GET /api/docs/health': () => ({ status: 200, data: { ok: true, ts: Date.now() } }),
  'POST /api/users': (req) => ({ status: 201, data: { ...req.body, id: Date.now() } }),
};

At runtime you’ll see logs like:

mock-http-interceptor.ts: Mock Request procesado: { method: 'GET', url: '/api/docs/health', matched: true }
mock-http-interceptor.ts: Mock Request procesado: { method: 'POST', url: '/api/admin/docs/save-folders-config', matched: false }

• matched: true → the mock answered.
• matched: false → the request reached the real server (persistence).

Summary

• The Mock API is a client‑side “pretend backend”.
• It does not persist on the server; for saving we use real endpoints.
• In docs-angular it’s active in development with fallbackToNetwork so real services (like config saving) continue to work.

How to move from mocks to a real API

1. Keep the same URL and method for the real endpoint (e.g., keep GET /api/items).
2. Return the same data shape the UI already expects.
3. Remove the corresponding entry from DocsMocks (or disable it). With fallbackToNetwork, the app will call the real server immediately.
4. Keep logging on temporarily to verify matched: false for those endpoints.
5. Add proper error codes at the server and verify the UI flows with real failures as well.