Core API (v2) Design & Middleware
Relevant source files
The following files were used as context for generating this wiki page:
The Core API (v2) of Harbor Next is designed using an API-first approach, where the RESTful interface is defined by a comprehensive OpenAPI (Swagger) specification. This design facilitates strong typing, automated code generation for both server-side handlers and client-side SDKs, and a clear separation between API definition and business logic.
The architecture relies on a middleware-driven request processing pipeline. This pipeline ensures that every request is subjected to consistent cross-cutting concerns, such as Object-Relational Mapping (ORM) context initialization, security verification, and authorization, before reaching the specific business logic implementers.
API Architecture & Code Generation
Harbor Next utilizes go-swagger to generate server-side boilerplate from the swagger.yaml definition. The generation process is managed via the build system and uses customized templates to enforce a specific interface-driven design.
Generation Workflow
The automated build process consumes the Swagger specification and produces Go models and rest-api interfaces. These interfaces are then implemented by developers to provide the actual service functionality.
The task gen-apis command executes the generation using specific initialisms like CVE, GC, and OIDC to ensure correct Go naming conventions.
Sources: taskfile/build.yml:138-154, tools/swagger/templates/README.md:8-25
Interface-Driven Design
The generated code exposes Go interfaces for every functional tag defined in the Swagger file (e.g., ProjectAPI, ArtifactAPI). This decoupling allows for:
- Dependency Injection: Business logic implementers can have their dependencies (databases, clients) injected during initialization.
- Extensibility: Implementations are separated from the generated boilerplate.
- Testability: API interfaces can be easily mocked for unit testing.
Sources: tools/swagger/templates/README.md:27-55
Middleware Request Pipeline
Every API request enters a chain of middleware that prepares the execution context. This mechanism ensures that resources are consistently available to the handlers.
The standard chain initialized in the core API includes orm.Middleware(), security.Middleware(), and security.UnauthorizedMiddleware().
Sources: src/core/api/harborapi_test.go:88-90
Key Middleware Components
| Component | Responsibility | Source |
|---|---|---|
| ORM Middleware | Initializes the database context and attaches it to the request lifecycle. | src/core/api/harborapi_test.go:89 |
| Security Middleware | Extracts credentials (Basic Auth, OIDC, or Session) and identifies the principal. | src/core/api/harborapi_test.go:89 |
| Unauthorized Middleware | Enforces policy and returns appropriate HTTP error codes if the principal lacks rights. | src/core/api/harborapi_test.go:89 |
| Inner Middleware | Custom executors that run after routing but before final binding and validation. | tools/swagger/templates/README.md:65-68 |
API V2 Endpoint Overview
The V2 API is structured around project-based management of OCI artifacts. Key functional areas include artifact management, project configuration, and security operations.
Major Endpoint Groups
| Category | Base Path | Primary Operations |
|---|---|---|
| Projects | /projects | Create, Update, Delete, List, and get Summary of projects. |
| Repositories | /repositories | List and manage image/artifact repositories. |
| Artifacts | /projects/{project_name}/repositories/{repository_name}/artifacts | CRUD operations on artifacts, including Copy, Tagging, and Labeling. |
| Scanning | /projects/.../artifacts/{reference}/scan | Trigger vulnerability and SBOM scans, retrieve reports. |
| Robot Accounts | /robots | Manage system and project level automation accounts. |
| Replication | /replication | Policy creation and execution for synchronizing with other registries. |
Sources: api/v2.0/swagger.yaml:14-1100
Authentication & Security Design
Security in the Core API is enforced through multiple layers defined in the specification and handled by the middleware.
Security Definitions
Harbor v2 supports multiple authentication schemes, primarily focusing on basic auth as defined in the global security requirements, though the middleware layer extends this to OIDC and Session-based cookies.
securityDefinitions:
basic:
type: basic
security:
- basic: []
- {}
Sources: api/v2.0/swagger.yaml:10-13
Authorization Logic
The Authorizer function within the API configuration is responsible for policy enforcement after the identity is established. It retrieves the principal from the context and checks it against the required scopes for the matched route.
- AuthToken: Extracts credentials (e.g., from a header) and returns a user representation.
- Authorizer: Validates if the authenticated user has permission to access the specific resource (e.g., specific Project ID).
Sources: tools/swagger/templates/README.md:144-177
Data Models & Constraints
The API uses strong typing for all request and response bodies. The Artifact model is the central entity, designed to support generic OCI types.
| Field | Type | Description |
|---|---|---|
digest | string | Unique content identifier of the artifact. |
type | string | Artifact type (e.g., image, chart). |
media_type | string | OCI media type. |
push_time | date-time | When the artifact was first uploaded. |
size | int64 | Total size in bytes. |
Sources: api/v2.0/swagger.yaml:1232-1279
Conclusion
The Core API (v2) Design and Middleware system provides a robust, scalable foundation for Harbor Next. By leveraging an API-first methodology with go-swagger, the project ensures consistency across its diverse feature set—ranging from basic repository management to complex security workflows like vulnerability scanning and P2P preheating. The middleware chain guarantees that security and data integrity are handled uniformly for every incoming request.