REST APIs & OpenAPI Spec
Relevant source files
The following files were used as context for generating this wiki page:
Hoop utilizes a comprehensive REST API architecture to manage access to infrastructure, including databases, servers, and cloud resources. This API serves as the backbone for the Hoop web application, CLI, and internal service communications. The system leverages the OpenAPI Specification (OAS) to define, generate, and validate its API contracts, ensuring consistency across different client implementations.
The API is structured around core resources such as Agents, Connections, Sessions, and Policies. It integrates security primitives directly into the protocol layer, allowing for features like real-time PII masking, command blocking, and human-in-the-loop approval workflows. The API is primarily implemented in Go using the Gin web framework, with OpenAPI documentation generated automatically from the source code annotations.
Sources: gateway/api/server.go:1-125, gateway/api/openapi/openapiv3.json, README.md:10-50
API Architecture & Routing
The Hoop API server is built using the Gin framework and handles multiple protocol groups beyond standard REST, including SSM and RDP proxies. The main API endpoints are prefixed with /api and are governed by various middleware for security, auditing, and authentication.
Server Configuration
The API server defaults to port 8009 and supports both HTTP and HTTPS (via TLS configuration). It serves static UI assets for the webapp while routing programmatic requests to specific handler groups.
This diagram illustrates the high-level request flow through the Hoop Gateway, highlighting the separation between standard API handlers and specialized protocol proxies.
Sources: gateway/api/server.go:126-174, gateway/api/server.go:183-200
Key Middleware
Every request to a protected endpoint passes through a chain of middleware:
- AuthMiddleware: Validates OIDC, SAML, or Local Auth tokens.
- AuditMiddleware: Records administrative actions (Create, Update, Delete) to the security audit log.
- CORSMiddleware: Manages Cross-Origin Resource Sharing for the web interface.
- SecurityHeaderMiddleware: Enforces standard security headers for browser-based clients.
Sources: gateway/api/server.go:140-150, gateway/api/server.go:210-250
OpenAPI Specification & Documentation
Hoop maintains a strict OpenAPI v3 specification that serves as the single source of truth for the API contract. The project uses the swag tool to parse Go code comments and generate the documentation.
Documentation Generation
The generation process is managed by a dedicated utility that outputs the specification to gateway/api/openapi/openapiv3.json. This file is then served by the gateway at /api/openapiv3.json.
func main() {
v3Spec, err := openapi.GenerateV3Spec()
if err != nil {
log.Fatal(err)
}
err = os.WriteFile("gateway/api/openapi/openapiv3.json", v3Spec, 0644)
if err != nil {
log.Fatal(err)
}
}
Sources: gateway/cmd/openapi-gen/main.go:1-18, gateway/api/server.go:203-204
Core Data Models
The OpenAPI spec defines several critical schemas used throughout the system:
| Model | Description | Key Fields |
|---|---|---|
| Connection | A target resource like a DB or SSH server. | name, type, subtype, agent_id, command |
| Session | An active or recorded interaction with a connection. | id, user_id, verb, status, event_stream |
| Agent | A remote process that executes commands in infrastructure. | id, name, mode, status, version |
| Review | A request for human approval of a risky operation. | id, status, min_approvals, review_groups_data |
Sources: gateway/api/openapi/openapiv3.json
Core REST Endpoints
The API is divided into functional domains, each handled by specific handler packages.
Connection Management
Connections define how users access infrastructure. The API supports full CRUD operations and testing connectivity via remote agents.
GET /api/connections: List all available connections with filtering by tags and type.POST /api/connections: Create a new connection associated with an agent.GET /api/connections/{id}/test: Trigger a connectivity test (ping) against the target.
Sources: gateway/api/server.go:420-460, gateway/api/openapi/openapiv3.json
Session & Execution
Sessions represent real-time interactions. The API handles both ad-hoc execution and interactive protocol tunneling.
POST /api/sessions: Start an ad-hoc execution (e.g., a SQL query or shell command).GET /api/sessions/{id}: Retrieve session metadata and event streams (input/output).GET /api/sessions/{id}/stream: Subscribe to a real-time Server-Sent Events (SSE) stream of session events.
Sources: gateway/api/server.go:680-730, gateway/api/openapi/openapiv3.json
Client Implementation & Utilities
Hoop provides client-side utilities to interact with these REST APIs efficiently, particularly within the CLI and the tunnel daemon.
API Resource Utility
The apiResource structure in the CLI facilitates dynamic endpoint construction and response decoding. It maps CLI resource types (e.g., "agents", "sa", "reviews") to their corresponding REST paths and methods.
This diagram shows how the CLI abstracts REST calls into a consistent internal resource model.
Sources: client/cmd/admin/apiutils.go:30-180
Tunnel Daemon (hsh-tunneld) IPC
The hsh-tunneld daemon exposes a local-only REST API over a Unix domain socket or named pipe. This API allows unprivileged UI components (like the tray icon) to control the privileged tunnel process.
| Path | Method | Description |
|---|---|---|
/v1/status | GET | Current daemon state (running, logged_in, version). |
/v1/connections | GET | List of tunnelable connections exposed as *.hoop. |
/v1/tunnel/up | POST | Bring the tunnel netstack online using persisted tokens. |
/v1/login/poll | GET | Poll the lifecycle of an OIDC login attempt. |
Sources: tunnel/ipc/openapi.yaml:120-250
Integration with WebApp V2 (React)
The modern React web application (webapp_v2) interacts with the REST APIs through a structured service layer. Each feature page follows a migration pattern where API calls are encapsulated in service files.
Service File Pattern
Service files use Axios to communicate with the Gateway. They are designed to be consumed by Zustand stores or React components.
// Example service structure derived from migration patterns
export const featureService = {
list: () => api.get('/feature-name'),
get: (id) => api.get(`/feature-name/${id}`),
create: (data) => api.post('/feature-name', data),
}
Sources: webapp_v2/MIGRATION_CHECKLIST.md:30-45
Conclusion
The REST APIs and OpenAPI specification form a robust foundation for the Hoop ecosystem. By centralizing logic in the Go-based gateway and enforcing API contracts via OpenAPI, Hoop ensures that complex security features—such as JIT reviews and PII masking—are applied consistently across the web app, CLI, and automated agents. The use of automated documentation generation and structured client utilities reduces the overhead of maintaining these interfaces as the project evolves.