HTTP::Method - HTTP Request Method and Common Properties according to RFC 7231


Version 0.03


    use HTTP::Method;
    # prefered instantiation
    my $get_mth = HTTP::Method->GET;
    # or from string
    my $str_mth = HTTP::Method->new(uc 'get');
    # testing
    if ( $mth->is_GET ) { ... }
    # introspection

or more intuative (and less strict!)

    use HTTP::Method ':case-insesitive';
    my $mth = HTTP::Method->new($str);
    printf "%s %s return the payload",
        $mth->is_head ? "does NOT" : "does";
                                    # "GET does return the payload"
                                    # "HEAD does NOT return the payload"


There is a lot to say about HTTP Methods in RFC 7231 Section 4. Request Methods. Most of the developers make the wrong assumption that it is just a 'uppercase string'. This module will help writing better code as it does validation and ensures right capitalization for the HTTP Method names.

As one could read in RFC 7231 Section 4.2 Common Method Properties HTTP Methods do have properties and can be divided in: Safe Methods, Idempotent Methods and Cacheable Methods. These properties are just predicate methods on a HTTP::Method object



Called when module is being used. This is used to set case-sensitivity.

    use HTTP::Method ':case-insensitive';

such that:

    my $str = 'get';                # or result from functioncall
    my $mth = HTTP::Method->new($str);
                                    # do not need to make uppercase
    my $del = HTTP::Method->DEL;    # prefer uppercase
    print $mth if $mth->is_get;     # prints "GET"
                                    # predicate method is lowercase


Creates a new HTTP::Method object. It takes only 1 argument, a HTTP-METHOD-NAME. It must be one of the methods defined in RFC 7231, SECTION 4.3. Method Definitions. Valid names are: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS and TRACE and additionally PATCH.

If used with :case-insensitive one can use lowercase names as well.



From "RFC 7231 Section 4.2.1. Safe Methods"

Request methods are considered "safe" if their defined semantics are essentially read-only; i.e., the client does not request, and does not expect, any state change on the origin server as a result of applying a safe method to a target resource. Likewise, reasonable use of a safe method is not expected to cause any harm, loss of property, or unusual burden on the origin server.


From "RFC 7231 Section 4.2.2. Idempotent Methods"

A request method is considered "idempotent" if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request. Of the request methods defined by this specification, PUT, DELETE, and safe request methods are idempotent.


From "RFC 7231 Section 4.2.2. Cachable Methods"

Request methods can be defined as "cacheable" to indicate that responses to them are allowed to be stored for future reuse; for specific requirements see [RFC7234]. In general, safe methods that do not depend on a current or authoritative response are defined as cacheable; this specification defines GET, HEAD, and POST as cacheable, although the overwhelming majority of cache implementations only support GET and HEAD.


HTTP::Method objects have an alternative way of instantiation. These help building more robust code. You can use HTTP::Method::HTTP-METHODE-NAME() for most HTTP methods like

    my $mth = HTTP::Method::HTTP-METHOD-NAME();
                                    # non OOP

use the OOP constructors:

    my $mth = HTTP::Method->HTTP-METHOD-NAME
                                    # prefered way

instead of

    my $mth = HTTP::Method->new(uc 'http-method-name')
                                    # don't do this

The list below shows which are available:




According to RFC 7231, SECTION 4.1 method tokens are case sensitive, unlike what most developers think it is. This might be surprising and will become very inconvenient if we had to think about it too much.

    use HTTP::Method ':case-insensitive';

Using the module this way will make it behave like we are most familiar with.

HTTP::Method->new($string) creates a new HTTP::Method object that will always have an uppercase name.

$mth = HTTP::Method->HTTP-METHOD-NAME factory methods will be uppercased.

$mth->is_http-method-name predicate methods are lowercased

"$mth" always stringfies to uppercase

If one does NOT use the import ':case-insensitive' The above behaviour will not be swithced on, resulting in some surprises

    my $str = 'get';
    my $mth = HTTP::Method->new($str);
                                    # croak "unknown method"
                                    # only uppercase http-method-names
    warn "case-sensitive" if $mth ne HTTP::Method->GET;
                                    # $mth stringifies to original $str
                                    # HTTP::Method->GET eq "GET"
    $mth->is_get;                   # undefined method
                                    # predicates are spelled according
                                    # to normilization, uppercase
                                    # $mth eq "get"
    $mth->is_GET;                   # undef
                                    # the internal token is lowercase
    $mth->is_method_cachable        # undef
                                    # 'get' is unknown to the RFC

Most of those could had been solved with passin in the right arument into the constructor, using uc like in

    my $mth = HTTP::Method->new(uc $str);
    print "$mth";                   # GET
    $mth->is_GET;                   # 1
    $mth->is_method_cachable;       # 1


Thank you Adam for inspiring me to write better readable code (don't look inside the source!)


Th. J. van Hoesel


Mohammad S. Anwar