HTTP

HTTP (atlas.http) is the package containing convenient abstractions for handling HTTP requests and responses inside the controller layer. It defines standard request parsing, validation, response formatting and access to the request's metadata (originated from API Gateway).

Below are the descriptions of both request and response abstractions.

HttpRequest

HttpRequest is a helper class designed to simplify the handling of HTTP requests in the controller layer (e.g., serverless AWS Lambda functions integrated with API Gateway).

It provides convenient access to path parameters, query string parameters, headers, request body, and authentication claims, along with validation and type conversion.

Attributes:

Name	Type	Description
path_params	dict	Path parameters extracted from the request.
query_params	dict	Query string parameters extracted from the request.
headers	dict	HTTP headers of the request.
raw_body	str	Raw string of the request body.
context	dict	The Lambda request context, including authorizer info.

body(dto_type=None)

Parses the request body as JSON and optionally validates it against a DTO class.

Parameters:

Name	Type	Description	Default
dto_type	type | None	A DTO class to validate the body against.	None

Returns:

Type	Description
dict | DTO	dict | DTO: The parsed request body as a dictionary or a DTO instance.

Raises:

Type	Description
ValidationError	If the body cannot be validated by the DTO.

claim(name, default=None)

Retrieves a claim from the Lambda authorizer context.

Parameters:

Name	Type	Description	Default
name	str	The claim name.	required
default	Any	The value to return if the claim is not present.	None

Returns:

Name	Type	Description
Any	Any	The claim value or the default.

get(key, default=None)

Retrieves a raw value from the original event dictionary.

Parameters:

Name	Type	Description	Default
key	str	The event key.	required
default	Any	Default value if the key is not present.	None

Returns:

Name	Type	Description
Any	Any	The value from the event or the default.

header(name, default=None)

Retrieves a header value by name.

Parameters:

Name	Type	Description	Default
name	str	The header name.	required
default	Any	The value to return if the header is not present.	None

Returns:

Name	Type	Description
Any	Any	The header value or the default.

path_param(name, type_=str, default=None)

Retrieves a path parameter by name and optionally converts it to the specified type.

Parameters:

Name	Type	Description	Default
name	str	The name of the path parameter.	required
type_	type	The expected Python type.	str
default	Any	The default value if the parameter is not found.	None

Returns:

Name	Type	Description
Any	Any	The parameter value converted to the specified type.

Raises:

Type	Description
BadRequestError	If the parameter is missing or cannot be converted to the expected type.

query_param(name, type_=str, default=None, required=False)

Retrieves a query string parameter by name with optional type conversion and requirement check.

Parameters:

Name	Type	Description	Default
name	str	The name of the query parameter.	required
type_	type	The expected Python type.	str
default	Any	The default value if the parameter is not present.	None
required	bool	If True, raises an error if the parameter is missing.	False

Returns:

Name	Type	Description
Any	Any	The parameter value converted to the specified type.

Raises:

Type	Description
BadRequestError	If the parameter is required but missing, or if type conversion fails.

HttpResponse

HttpResponse is a utility class for constructing HTTP responses in the controller layer (e.g., serverless AWS Lambda functions integrated with API Gateway).

It provides a single method to build properly formatted responses with status codes, JSON-serialized bodies, and standard headers.

build(status_code, body=None) staticmethod

Builds a HTTP response dictionary suitable for Lambda return values.

Parameters:

Name	Type	Description	Default
status_code	int	The HTTP status code for the response.	required
body	Any	The response body, which can be a string, dictionary, DTO, or any JSON-serializable object.	None

Returns:

Name	Type	Description
Dict	Dict[str, Any]	A dictionary containing "statusCode" (the HTTP status code), "body" (the response body serialized as a JSON string or an empty string if None), and "headers" (a dictionary containing application/json and CORS headers).