Methods

Preliminaries

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 HEAD, GET, PUT, DELETE, POST, PATCH, OPTIONS and TRACE.

Not every website needs all of these.

Websites that are designed to serve static files, only need HEAD, GET and OPTIONS. Websites that process form data need those three and POST as well. Websites that allow basic authoring capabilities using WebDAV further need PUT and 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 TRACE method.

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, HEAD and GET access to all resources by users with low privileges; but to allow PUT and 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 403.

Every configuration must include a methods entry — in either the server or 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.

Placement

The main 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.

Information Headers

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 rw-method-not-allowed.

When a CORS preflight request is made for a method that is not configured, the response fails with status code 403.

For the EBNF specifications of the RBAC, Router, and Cross Origin modules, refer to those documentation pages.

Cookbook

host {
    methods HEAD,GET,OPTIONS
}
								

host {
    methods HEAD,GET,POST,PUT,PATCH,DELETE,OPTIONS

    rbac {
        resources {
            `/rbac/credentials`  *methods=POST        *roles=anonymous
            `/rbac/free-pages`   *methods=GET,HEAD    *roles=anonymous
            `/rbac/free-pages`   *methods=PUT,DELETE  *roles=editor,devops
        }
    }
}
								

host {
    methods HEAD,GET,POST,PUT,PATCH,DELETE,OPTIONS

    router {
        `*.blue` *methods=GET,HEAD *module=/rwserve/dist/handlers/route/blue-handler.class.js
    }
}    
								

host {
    methods HEAD,GET,POST,PUT,PATCH,DELETE,OPTIONS
    
    request {
        cross-origin {
            `/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"
        }
    }
}