NAME
    Plack::Middleware::Negotiate - Apply HTTP content negotiation as Plack
    middleware

SYNOPSIS
        builder {
            enable 'Negotiate',
                formats => {
                    xml  => { 
                        type    => 'application/xml',
                        charset => 'utf-8',
                    },
                    html => { type => 'text/html', language => 'en' },
                    _    => { size => 0 }  # default values for all formats           
                },
                parameter => 'format', # e.g. http://example.org/foo?format=xml
                extension => 'strip';  # e.g. http://example.org/foo.xml
            $app;
        };

DESCRIPTION
    Plack::Middleware::Negotiate applies HTTP content negotiation to a PSGI
    request. In addition to normal content negotiation from a list of
    defined "formats" one may enable explicit format selection with a path
    "extension" or query "parameter". In summary, the following methods are
    tried in this order to negotiate a known format:

    HTTP GET/POST format parameter (if enabled with option "parameter")
        e.g. format is set to xml for http://example.org/foo?format=xml if
        format xml has been defined.

    URL path extension (if enabled with option "extension")
        e.g. format is set to xml for http://example.org/foo.xml if format
        xml has been defined.

    HTTP Accept Header (unless disabled with option "explicit")
        e.g. format is set to xml if format xml has been defined with
        content type application/xml for Accept header value
        "application/xml".

    The PSGI environment key "negotiate.format" is set to the chosen format
    name after negotiation. The PSGI response is enriched with corresponding
    HTTP headers Content-Type and Content-Language unless these headers
    already exist.

    If used as pure application, this middleware returns a HTTP status code
    406 if no format could be negotiated.

METHODS
  new( formats => { ... } [, %options ] )
    Creates a new negotiation middleware with a given set of formats.

  negotiate( $env )
    Chooses a format based on a PSGI request. The request is first checked
    for explicit format selection via "parameter" and "extension" (if
    configured) and then passed to HTTP::Negotiate. On success the method
    returns a format name. The method may modify the PSGI request
    environment keys PATH_INFO and SCRIPT_NAME if format was selected by
    extension set to "strip", and strips the "format" HTTP GET query
    parameter from QUERY_STRING if "parameter" is set to a format. If format
    was selected by HTTP POST body parameter, the parameter it is not
    stripped from the request.

  known( $format )
    Tells whether a format name is known. By default this is the case if the
    format name exists in the list of formats.

  about( $format )
    If the format was specified, this method returns a hash with "quality",
    "type", "encoding", "charset", and "language". Missing values are set to
    the default.

  variants
    Returns a list of content variants to be used in HTTP::Negotiate. The
    return value is an array reference of array references, each with seven
    elements: format name, source quality, type, encoding, charset,
    language, and size. The size is always zero.

  add_headers( \@headers, $format )
    Add apropriate HTTP response headers for a format unless the headers are
    already given.

CONFIGURATION
    formats
        A list of formats to choose among. Each format can be defined with
        "type", "quality" (defaults to 1), "encoding", "charset", and
        "language". The special format name "_" (underscore) is reserved to
        define default values for all formats.

        Formats can also be used to directly route the request to a PSGI
        application:

            my $app = Plack::Middleware::Negotiate->new(
                formats => {
                    json => { 
                        type => 'application/json',
                        app  => $json_app,
                    },
                    html => {
                        type => 'text/html',
                        app  => $html_app,
                    }
                }
            );

    parameter
        Enables explicit format selection with a query paramater, for
        instance "format". Both HTTP GET and HTTP POST body parameters are
        supported.

    extension
        Enables explicit format selection with a virtual file extension. The
        value "strip" strips a known format name from the request path. The
        value "keep" keeps the format name extension after format selection.

        The middleware takes care for rewriting and restoring PATH_INFO if
        it is configured to detect and strip a format extension.

    explicit
        Disables content negotiation based on HTTP headers.

LOGGING AND DEBUGGING
    Plack::Middleware::Negotiate uses "Log::Contextual" to emit a logging
    message during content negotiation on logging level "trace". Just set:

        $ENV{PLACK_MIDDLEWARE_NEGOTIATE_TRACE} = 1;

LIMITATIONS
    The Content-Encoding HTTP response header is not automatically set on a
    response and content negotiation based on size is not supported. Feel
    free to comment on whether and how this middleware should support both.

CONTRIBUTORS
    Jakob Voß, Christopher A. Kirke

COPYRIGHT AND LICENSE
    Copyright 2014- Jakob Voß

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO
    Content negotiation in this module is based on HTTP::Negotiate. See
    HTTP::Headers::ActionPack::ContentNegotiation for an alternative
    approach. This module has some overlap with
    Plack::Middleware::SetAccept.