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.