REST API & HTTP Handlers

Relevant source files

• cmd/intercmd.go
• cmd/serve_nonwindows.go
• cmd/serve_windows.go
• cmd/version.go
• cmd/winsc_nonwindows.go
• cmd/winsc_windows.go
• internal/app/app.go
• internal/domain/dtos/certificate.go
• internal/domain/dtos/notify.go
• internal/notify/service.go
• internal/rest/handlers/certificates.go
• internal/rest/handlers/notifications.go
• internal/rest/handlers/statistics.go
• internal/rest/handlers/workflows.go
• internal/rest/routes/routes.go
• internal/scheduler/scheduler.go
• internal/workflow/pbhook.go
• internal/workflow/pbjob.go
• internal/workflow/service_inst.go
• main.go
• migrations/1769313600_upgrade_v0.4.15.go
• pkg/core/deployer/providers/wangsu-cdnpro/wangsu_cdnpro.go
• pkg/core/notifier/providers/mattermost/mattermost.go
• pkg/sdk3rd/matrix/client.go
• pkg/sdk3rd/nginxproxymanager/types.go
• ui/src/api/certificates.ts
• ui/src/api/statistics.ts

Certimate builds a custom REST API layer on top of the PocketBase framework. While PocketBase provides automatic CRUD endpoints for all collections, Certimate implements specialized handlers for complex business logic such as certificate format conversion, ACME revocation, workflow orchestration, and notification testing.

API Architecture & Route Binding

The API is initialized during the PocketBase OnServe lifecycle hook. The router is organized into functional groups under the /api prefix, and all custom endpoints are protected by PocketBase's superuser authentication.

Initialization Flow

1. Bootstrap: The application entry point registers a function to the pb.OnServe() hook main.go65-76
2. Binding: routes.BindRouter is called, which initializes the required repositories and services including CertificateService, WorkflowService, StatisticsService, and NotifyService internal/rest/routes/routes.go23-35
3. Middleware: A group with the /api prefix is created, and the apis.RequireSuperuserAuth() middleware is applied internal/rest/routes/routes.go36-37
4. Handler Registration: Four primary handler groups are registered to this authenticated group internal/rest/routes/routes.go38-41

Route Registration Logic

Sources: main.go65-76 internal/rest/routes/routes.go23-43 internal/rest/handlers/statistics.go21-29

---

Handler Groups

1. Certificates Handler

Handles the retrieval and lifecycle management of issued SSL certificates.

• Download (POST /api/certificates/{certificateId}/download): Retrieves the certificate and private key in various formats (PEM, PFX, JKS). The handler binds the request body to dtos.CertificateDownloadReq internal/domain/dtos/certificate.go7-15
  • Implementation: The frontend calls this via ui/src/api/certificates.ts which sends the fileFormat and optional encoding parameters like pfxPassword or jksAlias ui/src/api/certificates.ts5-21
• Revoke (POST /api/certificates/{certificateId}/revoke): Interfaces with the ACME provider to invalidate a certificate.
  • Implementation: The frontend triggers this via the revoke function ui/src/api/certificates.ts23-27

2. Workflows Handler

Manages the manual execution and state of automation pipelines.

• Start Run (POST /api/workflows/{id}/runs): Manually triggers a workflow execution.
• Cancel Run (POST /api/workflows/{id}/runs/{runId}/cancel): Stops a currently running workflow instance.
• Stats (GET /api/workflows/stats): Returns the current concurrency level and lists of pending/processing run IDs.

3. Statistics Handler

Provides aggregated data for the dashboard.

• Get (GET /api/statistics): Returns a statistics object containing counts and statuses. It maintains a legacy route /statistics/get for backward compatibility internal/rest/handlers/statistics.go26-29 The frontend calls this via the get function in statistics.ts ui/src/api/statistics.ts5-11

4. Notifications Handler

Used for verifying communication channels.

• Test Push (POST /api/notifications/test-push): Sends a test message to verify credentials and channel configuration. The NotifyService is initialized with an AccessRepository to retrieve provider credentials internal/rest/routes/routes.go34
  • Logic: It validates that the Access record has Reserve == "notif" before proceeding internal/notify/service.go30-32

---

Request/Response Patterns

Certimate uses a consistent Data Transfer Object (DTO) pattern and a standard response wrapper via the resp package.

Standard Response Wrapper

All custom handlers return a response via resp.Ok(e, res) for success or resp.Err(e, err) for failures internal/rest/handlers/statistics.go34-37

Example: Notification Test Flow

The following diagram shows how a frontend request for a notification test travels through the system components.

Sources: internal/rest/routes/routes.go34-41 internal/notify/service.go25-50 internal/rest/handlers/statistics.go31-38

---

Implementation Details

Authentication and Security

All custom routes are bound to apis.RequireSuperuserAuth(), requiring a valid PocketBase Admin token internal/rest/routes/routes.go37

Data Transfer Objects (DTOs)

Request and response structures are strictly defined in the dtos package to decouple the API layer from internal domain models.

DTO Name	Purpose	File Reference
CertificateDownloadReq	ID and format (PFX/JKS/PEM) for export	internal/domain/dtos/certificate.go7-15
CertificateDownloadResp	Contains the zipBytes of the certificate	internal/domain/dtos/certificate.go17-19
NotifyTestPushReq	Access ID and provider for test alerts	internal/domain/dtos/notify.go

UI Integration

The React frontend interacts with these custom endpoints through dedicated API modules that wrap the httpPost and httpGet utilities. For example, ui/src/api/certificates.ts maps the UI's download function to the /api/certificates/${id}/download endpoint ui/src/api/certificates.ts5-21

API Call Mapping

Sources: ui/src/api/certificates.ts5-27 internal/rest/routes/routes.go23-42 internal/rest/handlers/statistics.go21-38

Sources: main.go65-76 internal/rest/routes/routes.go23-43 internal/rest/handlers/statistics.go21-38 internal/domain/dtos/certificate.go7-26 ui/src/api/certificates.ts5-27 ui/src/api/statistics.ts5-11 internal/notify/service.go25-50