# `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 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.