API Reference
2 minute read
Router
router.New(opts ...Option) *Router
Creates a new router instance.
r := router.New()
// With options
r := router.New(
router.WithTracing(),
router.WithTracingServiceName("my-api"),
)
HTTP Method Handlers
Register routes for HTTP methods:
r.GET(path string, handlers ...HandlerFunc) *Route
r.POST(path string, handlers ...HandlerFunc) *Route
r.PUT(path string, handlers ...HandlerFunc) *Route
r.DELETE(path string, handlers ...HandlerFunc) *Route
r.PATCH(path string, handlers ...HandlerFunc) *Route
r.OPTIONS(path string, handlers ...HandlerFunc) *Route
r.HEAD(path string, handlers ...HandlerFunc) *Route
Example:
r.GET("/users", listUsersHandler)
r.POST("/users", createUserHandler)
r.GET("/users/:id", getUserHandler)
Middleware
r.Use(middleware ...HandlerFunc)
Adds global middleware to the router.
r.Use(Logger(), Recovery())
Route Groups
r.Group(prefix string, middleware ...HandlerFunc) *Group
Creates a new route group with the specified prefix and optional middleware.
api := r.Group("/api/v1")
api.Use(Auth())
api.GET("/users", listUsers)
API Versioning
r.Version(version string) *Group
Creates a version-specific route group.
v1 := r.Version("v1")
v1.GET("/users", listUsersV1)
Static Files
r.Static(relativePath, root string)
r.StaticFile(relativePath, filepath string)
r.StaticFS(relativePath string, fs http.FileSystem)
Example:
r.Static("/assets", "./public")
r.StaticFile("/favicon.ico", "./static/favicon.ico")
Route Introspection
r.Routes() []RouteInfo
Returns all registered routes for inspection.
Route
Constraints
Apply validation constraints to route parameters:
route.WhereInt(param string) *Route
route.WhereFloat(param string) *Route
route.WhereUUID(param string) *Route
route.WhereDate(param string) *Route
route.WhereDateTime(param string) *Route
route.WhereEnum(param string, values ...string) *Route
route.WhereRegex(param, pattern string) *Route
Example:
r.GET("/users/:id", getUserHandler).WhereInt("id")
r.GET("/entities/:uuid", getEntityHandler).WhereUUID("uuid")
r.GET("/status/:state", getStatusHandler).WhereEnum("state", "active", "pending")
Group
Route groups support the same methods as Router, with the group’s prefix automatically prepended.
group.GET(path string, handlers ...HandlerFunc) *Route
group.POST(path string, handlers ...HandlerFunc) *Route
group.Use(middleware ...HandlerFunc)
group.Group(prefix string, middleware ...HandlerFunc) *Group
HandlerFunc
type HandlerFunc func(*Context)
Handler function signature for route handlers and middleware.
Example:
func handler(c *router.Context) {
c.JSON(200, map[string]string{"message": "Hello"})
}
Errors
The router package defines sentinel errors for routing, binding, and server concerns. Use errors.Is(err, router.Err...) to check for them.
| Sentinel | Description |
|---|---|
ErrContextResponseNil | Context response is nil |
ErrContentTypeNotAllowed | Content type is not allowed |
ErrResponseWriterNotHijacker | ResponseWriter does not implement http.Hijacker |
ErrBloomFilterSizeZero | Bloom filter size must be non-zero |
ErrBloomHashFunctionsInvalid | Bloom hash functions must be positive |
ErrVersioningConfigInvalid | Versioning configuration is invalid |
ErrServerTimeoutInvalid | Server timeout must be positive |
ErrRoutesNotFrozen | Routes have not been frozen yet |
ErrRouteNotFound | Route not found |
ErrMissingRouteParameter | Missing required route parameter |
ErrExpectedJSONArray | Expected a JSON array |
ErrArrayExceedsMax | Array exceeds maximum items |
ErrQueryInvalidInteger | Query parameter contains an invalid integer |
Validation-related errors (e.g. from c.Bind or c.Validate) are not in the router package. Use rivaas.dev/validation and errors.As(err, &validation.Error) or errors.Is(err, validation.ErrValidation).
Next Steps
- Context API: See all Context methods
- Options: Review Router options
- Constraints: Learn about route constraints
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.