How a user-agent can discover the allowable methods
Allow
Preliminaries
This note describes how a user-agent can discover the allowable methods, and how the server responds to methods it can not handle.
Each server resource can be accessed with one or more of the following methods: HEAD
, GET
, PUT
, DELETE
, POST
, PATCH
, OPTIONS
and TRACE
.
The HTTP specification provides a mechanism for a user agent to discover which of these methods are allowed on a particular resource through the OPTIONS
method.
As an example, if the user agent wants to discover which methods are available for the resource at https://example.com/customer/names
, an OPTIONS
request can be sent to that URL, and the response will contain an allow
header listing the available methods, which may look like:
allow: HEAD,GET,OPTIONS
Normally, the list of allowable methods returned in the allow
header is the list of methods configured by the webmaster in the methods
entry. But not always. When the RBAC Module is enabled, access to resources is restricted on a path-pattern basis. Each path-pattern specifies a list of allowable methods and the roles that are permitted to use those methods. An OPTIONS
request in this circumstance may return a smaller set of allowable methods.
Server Options
If a user agent wants to query the server for the list of allowable methods, without limiting it to a resource path, a bare '*'
may be issued to the server like this https://example.com/*
. The server will respond with an allow
header equivalent to the values configured by the webmaster in the methods
entry.
Response code 405
Whenever any request method — other than OPTIONS
— cannot be fulfilled, the server returns status code 405
with an allow
header listing the methods that are allowed. When the OPTIONS
methods itself is not enabled by the webmaster, the response will have status code 405
and no allow
response header will be present.
Configuration
There are no special configuration settings for the allow
header. Its behavior is defined by IETF RFC 7231 HTTP/1.1 Semantics and Content Section 7.4.1.
Review
Key points to remember:
- The
OPTIONS
method should be included in themethods
entry of every production server. - The
allow
response header lists the methods allowed on a particular resource. - The RBAC module may limit the methods allowed on a resource.