Declaring which HTTP methods are acceptable and applicable
This note describes the different configuration options that govern which HTTP methods are acceptable and applicable at the host level, and how to limit methods on resources that match a path-pattern.
The standard HTTP methods are
Not every website needs all of these.
Websites that are designed to serve static files, only need
OPTIONS. Websites that process form data need those three and
POST as well. Websites that allow basic authoring capabilities using WebDAV further need
DELETE. And websites that provide interactive capabilities using AJAX may want to implement
PATCH as well. Finally, for debugging purposes, a webmaster may want to temporarily enable the
Each host configuration should declare which methods it is prepared to handle. If no such declaration is made in the
host section, the methods declared in the
server section will be used as a fallback.
Over and above this basic declaration, there are several configuration sections that further restrict which methods are allowed or applicable.
The RBAC module defines role based access to resource patterns. Those definitions include a parameter that lists the methods that are applicable to the given RBAC resource/role pair. In this way it is possible to allow for example,
GET access to all resources by users with low privileges; but to allow
DELETE access only to users with elevated privileges.
The Router module defines supplementary processing modules to be called when resource requests match a given resource pattern. Those definitions include a parameter that lists the methods that are applicable to the router definition. In this way it is possible to allow for example, a
POST request to a URL to be sent to an API module for updating data, while a
GET request to the same URL might be sent to a different API module for retrieving the data.
The Cross Origin module defines CORS rules. In some preflight requests the requestor may ask for permission to use a method other than
GET. Unless the configuration explicitly allows those other methods, the CORS response will be
Every configuration must include a
methods entry — in either the
host section — to declare which methods it supports. The methods should be spelled with all capital letters, and concatenated using commas, without intervening whitespace.
When methods are further refined in module configurations, they use a
*methods attribute to list which methods are applicable. This applies to the RBAC, Router, and Cross Origin modules. The syntax for these attributes is the same as for the main methods declaration: capitalized words and comma-separated values.
methods declaration section is typically placed in the
host section, but when not present, the declaration in the
server section will be used. Values appearing in both are never merged; the
host section's takes precedence.
When a request is received for a resource that is not configured to allow the given method, the response fails with status code
405 and information header
When a CORS preflight request is made for a method that is not configured, the response fails with status code
|method-name||::=||'HEAD' | 'GET' | 'PUT' | 'DELETE' | 'POST' | 'PATCH' | 'OPTIONS' | 'TRACE'|
|methods-entry||::=||'methods' SP (method-name COMMA)* CR|
For the EBNF specifications of the RBAC, Router, and Cross Origin modules, refer to those documentation pages.
Example 1: Typical methods declaration
Example 2: Distinct methods based on RBAC roles
`/rbac/credentials` *methods=POST *roles=anonymous
`/rbac/free-pages` *methods=GET,HEAD *roles=anonymous
`/rbac/free-pages` *methods=PUT,DELETE *roles=editor,devops
Example 3: Selected methods for routed modules
`*.blue` *methods=GET,HEAD *module=/rwserve/dist/handlers/route/blue-handler.class.js
Example 4: CORS methods
`/cors/trusted-host-A` *methods=OPTIONS,GET,PUT *origin="trusted-host-a.com"
`/cors/trusted-host-B` *methods=OPTIONS,GET,PUT *origin="trusted-host-b.com"
Key points to remember:
- Always include a declaration of the methods allowed.
- Refine the list of applicable methods for path-patterns using a
- Configure the server to use the smallest set of HTTP methods possible, to block illegitimate requests.