README
¶
MethodOverride
Let clients send PUT, PATCH, or DELETE using a POST request plus a header or form field. Useful when the client cannot use real HTTP methods (for example HTML forms, which only support GET and POST).
Full docs: Middleware Guide and Middleware Reference.
Features
- Override method via
X-HTTP-Method-Overrideheader (default) - Override via form field (e.g.
_method) for POST form submissions - Choose which methods can be overridden (default: PUT, PATCH, DELETE)
- Optional: only allow override on POST requests
- Optional: require CSRF token when using form-based override
Installation
go get rivaas.dev/middleware/methodoverride
Requires Go 1.25 or later.
Quick Start
package main
import (
"net/http"
"rivaas.dev/router"
"rivaas.dev/middleware/methodoverride"
)
func main() {
r := router.New()
r.Use(methodoverride.New())
r.DELETE("/users/:id", func(c *router.Context) {
id := c.Param("id")
c.JSON(http.StatusOK, map[string]string{"deleted": id})
})
http.ListenAndServe(":8080", r)
}
Clients can send a POST with the real method in a header:
curl -X POST http://localhost:8080/users/123 \
-H "X-HTTP-Method-Override: DELETE"
Configuration
| Option | What it does |
|---|---|
WithHeader |
Header name for method override (default: X-HTTP-Method-Override) |
WithQueryParam |
Query or form field name (default: _method); set empty to disable |
WithAllow |
Methods that can be set via override (default: PUT, PATCH, DELETE) |
WithOnlyOn |
Only treat override when the request method is one of these (default: POST) |
WithRequireCSRFToken |
When true, form-based override only if request is considered CSRF-verified |
Example with custom header and form field:
r.Use(methodoverride.New(
methodoverride.WithHeader("X-Method-Override"),
methodoverride.WithQueryParam("_method"),
))
Example in HTML forms
<form method="POST" action="/users/123">
<input type="hidden" name="_method" value="DELETE">
<button type="submit">Delete user</button>
</form>
Security note
Use method override only when you need it (e.g. form limitations). For form-based override, consider CSRF protection; the middleware can require CSRF verification via WithRequireCSRFToken.
Examples
A runnable example is in the example/ directory:
cd example
go run main.go
Learn More
- Middleware overview – All middleware and recommended order
- TrailingSlash middleware – Normalize trailing slashes in URLs
License
Apache License 2.0 – see LICENSE for details.
Documentation
¶
Overview ¶
Package methodoverride provides middleware for HTTP method override, allowing clients to use POST requests with a header or form field to specify the actual HTTP method (PUT, DELETE, etc.).
This middleware enables RESTful APIs to work with clients that don't support all HTTP methods (e.g., HTML forms only support GET and POST). It's commonly used for PUT and DELETE operations from web forms.
Basic Usage ¶
import "rivaas.dev/middleware/methodoverride" r := router.MustNew() r.Use(methodoverride.New())
Method Override Sources ¶
The middleware checks for method override in the following order:
- X-HTTP-Method-Override header (default)
- _method form field (for POST requests with form data)
- X-HTTP-Method header (alternative header name)
Configuration Options ¶
- HeaderName: Custom header name for method override (default: X-HTTP-Method-Override)
- FormFieldName: Custom form field name (default: _method)
- AllowedMethods: Methods allowed to be overridden (default: PUT, PATCH, DELETE)
Example Usage ¶
Clients can override methods using headers:
POST /users/123 HTTP/1.1 X-HTTP-Method-Override: DELETE
Or using form fields:
<form method="POST" action="/users/123">
<input type="hidden" name="_method" value="DELETE">
<button type="submit">Delete</button>
</form>
Security Considerations ¶
Method override should only be used when necessary (e.g., HTML form limitations). Consider CSRF protection when using form-based method override. The middleware can be checked via CSRFVerified(c) when using WithRequireCSRFToken.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CSRFVerified ¶
CSRFVerified returns true if a CSRF verification middleware has set the verified flag in context. Other middleware (e.g., CSRF middleware) should set the flag via context when CSRF is verified.
func New ¶
func New(opts ...Option) router.HandlerFunc
New creates a new HTTP method override middleware.
This middleware allows clients to override the HTTP method using a header or query parameter, which is useful for HTML forms that only support GET/POST.
SECURITY WARNING: This middleware should only be used when you control the client (e.g., HTML forms). Never enable for public APIs without WithRequireCSRFToken(true), as it can be exploited for CSRF attacks.
Basic usage:
r.Use(methodoverride.New())
With CSRF protection:
r.Use(csrf.Verify()) // Sets CSRF verification flag
r.Use(methodoverride.New(
methodoverride.WithRequireCSRFToken(true),
methodoverride.WithAllow("PUT", "PATCH", "DELETE"),
methodoverride.WithOnlyOn("POST"),
))
Custom header:
r.Use(methodoverride.New(
methodoverride.WithHeader("X-HTTP-Method"),
))
func OriginalMethod ¶
OriginalMethod retrieves the original HTTP method before override. Returns the current method if no override occurred.
Types ¶
type Option ¶
type Option func(*config)
Option defines functional options for method override middleware configuration.
func WithAllow ¶
WithAllow sets the allowlist of HTTP methods that can be overridden. Default: ["PUT", "PATCH", "DELETE"]
Example:
methodoverride.New(methodoverride.WithAllow("PUT", "PATCH", "DELETE", "HEAD"))
func WithHeader ¶
WithHeader sets the header name for method override. Default: "X-HTTP-Method-Override"
Example:
methodoverride.New(methodoverride.WithHeader("X-HTTP-Method"))
func WithOnlyOn ¶
WithOnlyOn sets which HTTP methods can trigger method override. Default: ["POST"] Only requests with these methods will be checked for override.
Example:
methodoverride.New(methodoverride.WithOnlyOn("POST", "GET"))
func WithQueryParam ¶
WithQueryParam sets the query parameter name for method override. Default: "_method" Set to empty string to disable query parameter support.
Example:
methodoverride.New(methodoverride.WithQueryParam("_method"))
func WithRequireCSRFToken ¶
WithRequireCSRFToken requires CSRF token verification before allowing method override. When enabled, the middleware expects a CSRF verification middleware to run first and set the context so CSRFVerified(c) returns true. Default: false
SECURITY WARNING: This middleware should only be used when you control the client (e.g., HTML forms). Never enable for public APIs without RequireCSRFToken=true, as it can be exploited for CSRF attacks.
Example:
r.Use(csrf.Verify()) // Sets CSRF verification flag r.Use(methodoverride.New(methodoverride.WithRequireCSRFToken(true)))
func WithRespectBody ¶
WithRespectBody requires a request body for method overrides. When enabled, requests without a body will not be overridden. Default: false
Example:
methodoverride.New(methodoverride.WithRespectBody(true))
Source Files