.. _library_http_parameters:

``http_parameters``
===================

The ``http_parameters`` library provides typed query, form, path,
header, and cookie parameter extraction helpers for normalized HTTP
requests together with an optional router companion category that reuses
the same declarations for OpenAPI metadata generation.

Currently this library provides:

- object ``http_parameters``
- category ``http_router_parameters``

API documentation
-----------------

Open the
`../../apis/library_index.html#http_parameters <../../apis/library_index.html#http_parameters>`__
link in a web browser.

Loading
-------

To load the library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(http_parameters(loader)).

Testing
-------

To test this library, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(http_parameters(tester)).

Declarations
------------

Parameter declarations use the shape:

::

   parameter(Name, Source, Type, Options)

The currently supported source atoms are:

- ``query``
- ``form``
- ``path``
- ``header``
- ``cookie``

Header declarations match normalized request headers case-insensitively.
Cookie declarations read from the normalized ``cookies(Pairs)`` request
property already exposed by the ``http_core`` library. Reserved OpenAPI
header names such as ``accept``, ``content_type``, and ``authorization``
remain available for runtime extraction but are omitted from generated
OpenAPI parameter descriptors.

The currently supported scalar types are:

- ``string``
- ``text``
- ``atom``
- ``integer``
- ``number``
- ``boolean``

List-valued declarations use ``list(ScalarType)``.

The currently supported options are:

- ``optional``
- ``default(Value)``
- ``description(Description)``
- ``schema(Schema)``
- ``enum(Values)``
- ``minimum(Value)``
- ``maximum(Value)``
- ``pattern(Pattern)``

The ``enum/1``, ``minimum/1``, and ``maximum/1`` options are enforced at
runtime after type coercion. For list-valued declarations they apply to
each extracted item. Defaults are also checked against these constraints
when declarations are normalized.

The ``minimum/1`` and ``maximum/1`` options are only valid for
``integer`` and ``number`` declarations. The ``pattern/1`` option is
only valid for ``string``, ``text``, and ``atom`` declarations and is
currently used only to enrich the generated OpenAPI schema; it is not
enforced at runtime.

Duplicate declaration pairs with the same ``(Name, Source)`` are
rejected.

Path declarations must remain scalar and cannot use ``default/1``. When
the library is used through ``http_router_parameters``, any declared
``path`` parameter must match a placeholder in the route path template.
Typed route placeholders remain authoritative for runtime type
compatibility:

- ``{name:integer}`` requires a declared runtime type of ``integer``
- ``{name:number}`` requires a declared runtime type of ``number``
- ``{name}`` allows declared runtime types ``string``, ``text``, or
  ``atom``

Descriptions and custom ``schema/1`` values can still refine the
generated OpenAPI descriptor for a matching path parameter, but they
cannot rename the placeholder or change its runtime type.

Error handling
--------------

Client-input validation failures throw exceptions using the shape:

::

   error(http_parameter_validation(Errors), Context)

The ``Errors`` list currently contains these structured terms:

- ``missing_parameter(Source, Name)``
- ``duplicate_parameter(Source, Name)``
- ``invalid_parameter_value(Source, Name, Value, Reason)``

The ``Reason`` term is currently one of:

- ``expected(Type)``
- ``incompatible_type(Type)``
- ``not_in_enum(Values)``
- ``below_minimum(Minimum)``
- ``above_maximum(Maximum)``
- ``invalid_list_item(Index, ItemReason)``

Even though the public API currently fails fast, the list-shaped
contract keeps error detection and reporting decoupled and leaves room
for future accumulated validation without changing router integration.

Router integration
------------------

The ``http_router_parameters`` category extends ``http_router`` and
adds:

- ``route_parameters/2``
- ``route_parameter_declarations/2``
- ``route_parameter_request_body_description/2``
- ``route_parameter_extra_metadata/2``

The category generates OpenAPI parameter descriptors for ``query``,
``path``, ``header``, and ``cookie`` declarations,
``application/x-www-form-urlencoded`` request bodies for ``form``
declarations, and a default ``400 Bad Request`` response descriptor.
When a declaration uses ``enum/1``, ``minimum/1``, ``maximum/1``, or
``pattern/1``, the generated parameter or form-property schema reflects
those constraints when the schema is generated by the library.

When ``route_parameter_extra_metadata/2`` also defines ``responses/1``,
an explicit ``response(400, ...)`` replaces the generated validation
response. A ``response(default, ...)`` remains additive and does not
suppress the generated ``400 Bad Request`` descriptor.
