REST API endpointy

Všechny API endpointy jsou dostupné pod prefixem /api/v1/. Swagger dokumentace je přístupná na http://localhost:4405/docs.

Verzování

// V main.ts
app.enableVersioning({
  type: VersioningType.URI,
  defaultVersion: '1',
  prefix: 'api/v',
});
// Výsledná URL: /api/v1/auth/login

Přehled controllerů

Doménové controllery

Controller	Route prefix	Autentizace	Klíčové endpointy
AuthController	`/auth`	Smíšená	register, login, magic-link, OAuth, me, switch-role
UsersController	`/users`	Roles(ADMIN)	CRUD, aktivace/deaktivace
CoursesController	`/courses`	Smíšená	CRUD, publish, cancel, tým, kanban
BookingsController	`/bookings`	JWT	CRUD, confirm, cancel, recenze, statistiky
InstructorsController	`/instructors`	Smíšená	CRUD, approve, reject, suspend, certifikace
CompaniesController	`/companies`	JWT	CRUD, členové, ověření, pozastavení

Kurzy -- podcontrollery

Controller	Route prefix	Autentizace	Popis
CourseGenerationController	`/courses/generate`	Roles(ADMIN, GARANT)	Generování kurzů, náhled, fronta
CourseProposalsController	`/course-proposals`	Roles(ADMIN, GARANT)	Návrhy kurzů ke schválení
ReplacementController	`/replacements`	Roles(ADMIN, GARANT, INSTRUCTOR)	Náhrady instruktorů
WithdrawalController	`/withdrawals`	JWT	Žádosti o odstoupení z kurzu
GenerationLogsController	`/generation-logs`	Roles(ADMIN, GARANT)	Logy generovacího algoritmu

Podpůrné controllery

Controller	Route prefix	Autentizace	Popis
SalesController	`/sales`	Roles(SALES_REP, ADMIN)	B2B leady, aktivity, pipeline
SimpleAvailabilityController	`/simple-availability`	Roles(INSTRUCTOR)	Správa dostupnosti
RegionsController	`/regions`	Smíšená	Kraje, oblastní spolky, garanti
PaymentsController	`/payments`	Smíšená	Stripe webhook, platby, faktury
NotificationsController	`/notifications`	JWT	In-app notifikace
FilesController	`/files`	JWT	Nahrávání souborů

Integrační controllery

Controller	Route prefix	Autentizace	Popis
AresController	`/ares`	Veřejný	Vyhledávání v obchodním rejstříku
VerifyController	`/verify`	JWT	SMS ověření telefonu
MagicActionsController	`/actions`	Veřejný	Akce z e-mailu (potvrzení/odmítnutí)
GeoController	`/geo`	Smíšená	Města, pokrytí instruktorů, H3
DocsChatController	`/docs`	Veřejný (rate-limited)	AI chat asistent pro dokumentaci
HealthController	`/`	Veřejný	Health check (`GET /api/v1/health`)

Vzor controlleru

@ApiTags('feature')
@Controller('feature')
export class FeatureController {
  constructor(private featureService: FeatureService) {}

  @Get()
  @ApiOperation({ summary: 'Seznam záznamů' })
  findAll() {
    return this.featureService.findAll();
  }

  @Post()
  @UseGuards(JwtAuthGuard, RolesGuard)
  @Roles(UserRole.ADMIN)
  @ApiBearerAuth()
  @ApiOperation({ summary: 'Vytvořit záznam' })
  create(@Body() dto: CreateFeatureDto, @CurrentUser() user: User) {
    return this.featureService.create(dto, user);
  }
}

DTO vzor (class-validator)

export class CreateUserDto {
  @ApiProperty({ example: 'jan@example.com' })
  @IsEmail()
  email: string;

  @ApiProperty({ minLength: 8 })
  @IsString()
  @MinLength(8)
  password: string;

  @ApiPropertyOptional()
  @IsOptional()
  @IsString()
  phone?: string;

  @ApiProperty({ enum: UserRole })
  @IsEnum(UserRole)
  role: UserRole;
}

Každá vlastnost DTO musí mít dekorátor @ApiProperty() nebo @ApiPropertyOptional(). Bez něj Orval vygeneruje { [key: string]: unknown } místo správného typu.

Globální validace

// V main.ts
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,              // Odstraní neznámé vlastnosti
    forbidNonWhitelisted: true,   // Vrátí 400 při neznámých vlastnostech
    transform: true,              // Automatická transformace typů
    transformOptions: {
      enableImplicitConversion: true,  // "1" v query stringu -> number 1
    },
  })
);

Formát chybové odpovědi

{
  "statusCode": 400,
  "message": ["email musí být platný email", "heslo musí mít alespoň 8 znaků"],
  "error": "Bad Request",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "path": "/api/v1/users"
}

Guardy a dekorátory

Guard/Dekorátor	Účel	Použití
`JwtAuthGuard`	Ověření JWT tokenu	`@UseGuards(JwtAuthGuard)`
`RolesGuard`	Kontrola role uživatele	`@UseGuards(RolesGuard)` + `@Roles(...)`
`@CurrentUser()`	Získání autentizovaného uživatele	`@CurrentUser() user: User`
`@CurrentUser('id')`	Získání konkrétní vlastnosti	`@CurrentUser('id') userId: string`
`@Roles(...)`	Požadované role	`@Roles(UserRole.ADMIN)`
`@Public()`	Přeskočení autentizace	Na handler/class

JwtAuthGuard musí být vždy před RolesGuard -- @UseGuards(JwtAuthGuard, RolesGuard). Opačné pořadí způsobí chybu.

CORS

API podporuje tři frontendové originy (FRONTEND_URL + ADMIN_URL + DOCS_URL), všechny s credentials: true pro cross-origin cookies.

Swagger dokumentace

Přístupná na http://localhost:4405/docs. OpenAPI specifikace se automaticky exportuje do apps/api/openapi.json po startu serveru (v development režimu).

// Dekorátory pro Swagger
@ApiTags('auth')                      // Skupina endpointů
@ApiOperation({ summary: 'Přihlášení' })  // Popis operace
@ApiResponse({ status: 200, description: 'Úspěch' })
@ApiBearerAuth()                      // Vyžaduje autentizaci

On this page