apijuice

Documentation

Overview

Description: This package provides utility functions for writing JSON responses and checking mandatory query parameters.

Index

• func BuildQueryString(params ...string) string
• func CheckMandatoryQueryParams(queryParams map[string][]string, mandatoryQueryParams ...*QueryParam) error
• func ServeHTML(w http.ResponseWriter, htmlContent io.Reader, code int)
• func WriteErrorResponse(w http.ResponseWriter, errorCode int, escapeHTML bool)
• func WriteGzipErrorResponse(w http.ResponseWriter, errorCode int, escapeHTML bool)
• func WriteGzipJSONResponse(w http.ResponseWriter, data interface{}, code int, escapeHTML bool) error
• func WriteJSONResponse(w http.ResponseWriter, data interface{}, code int, escapeHTML bool) error
• type QueryParam

Functions

func BuildQueryString

func BuildQueryString(params ...string) string

BuildQueryString constructs a query parameter string from a variadic number of key-value pairs.

The values passed should not already be URL-escaped, as the function will handle escaping.

If an uneven number of parameters is passed, the function will use "N/A" as the value for the last key.

Example usage:

query := BuildQueryParams("q", "value1", "name", "John Doe", "age")
fmt.Println(query) // Output: ?q=value1&name=John+Doe&age=N%2FA

func CheckMandatoryQueryParams

func CheckMandatoryQueryParams(queryParams map[string][]string, mandatoryQueryParams ...*QueryParam) error

CheckMandatoryQueryParams is a function that validates the presence and values of mandatory query parameters in a given request. It takes a map of query parameters and a variadic slice of QueryParam pointers as arguments.

The function iterates over each QueryParam in the mandatoryQueryParams slice and checks if its key is present in the queryParams map. If the key is not present and the Optional field of the QueryParam is set to false, an error is returned indicating that the query parameter is mandatory. If the key is not present but the Optional field of the QueryParam is set to true, the function skips the checks and continues with the next query parameter.

For each query parameter that is present, the function checks if its values are valid according to the following rules:

• The value cannot be an empty string.
• The value must be one of the accepted values if the AcceptedValues field of the QueryParam is not nil and has at least one element.
• The value cannot be a duplicate of a previously seen value for the same key.
• If the MultipleValuesAllowed field of the QueryParam is set to false, the query parameter cannot have more than one value.

If any of these checks fail, an error is returned with a message indicating the nature of the failure. If all checks pass, the function returns nil, indicating that all mandatory query parameters are present and their values are valid.

func ServeHTML

func ServeHTML(w http.ResponseWriter, htmlContent io.Reader, code int)

ServeHTML writes an HTML response to the provided http.ResponseWriter with the given HTML content and HTTP status code.

Parameters:

• w: http.ResponseWriter to write the response to.
• htmlContent: HTML content to be sent as the response payload.
• code: HTTP status code to be set in the response.

func WriteErrorResponse

func WriteErrorResponse(w http.ResponseWriter, errorCode int, escapeHTML bool)

WriteErrorResponse writes an error response to the response writer with appropriate headers.

It does NOT return an error because it is used to write an error response.

Instead, if an error occurs internally, it writes the error to the response writer with http.Error.

func WriteGzipErrorResponse

func WriteGzipErrorResponse(w http.ResponseWriter, errorCode int, escapeHTML bool)

WriteGzipErrorResponse writes an error response to the response writer with appropriate headers.

It does NOT return an error because it is used to write an error response.

Instead, if an error occurs internally, it writes the error to the response writer with http.Error.

This method does NOT check for the Accept-Encoding header.

This method overrides the Content-Length header with the length of the compressed data.

Use this method only if you are sure that the client can handle gzip compression.

func WriteGzipJSONResponse

func WriteGzipJSONResponse(w http.ResponseWriter, data interface{}, code int, escapeHTML bool) error

WriteGzipJSONResponse compresses the JSON data and writes it to the response writer with appropriate headers.

The Content-Encoding header is set to gzip and the Content-Type header is set to application/json.

The Content-Length header is set with the length of the compressed data.

The status code is set based on the provided code parameter.

If the data cannot be serialized to JSON, an error is returned.

If the compressed data cannot be written to the response writer, an error is returned.

This method does NOT check for the Accept-Encoding header.

This method overrides the Content-Length header with the length of the compressed data.

Use this method only if you are sure that the client can handle gzip compression.

func WriteJSONResponse

func WriteJSONResponse(w http.ResponseWriter, data interface{}, code int, escapeHTML bool) error

WriteJSONResponse writes the JSON data to the response writer with appropriate headers.

The Content-Type header is set to application/json.

The Content-Length header is set with the length of the uncompressed data.

The Content-Lenght is not set if the Content-Encoding header is set to gzip.

The status code is set based on the provided code parameter.

If the data cannot be serialized to JSON, an error is returned.

If the uncompressed data cannot be written to the response writer, an error is returned.

Types

type QueryParam

type QueryParam struct {
	Key                   string
	Value                 string
	MultipleValuesAllowed bool
	AcceptedValues        []string
	Optional              bool
}

QueryParam represents a query parameter that can be checked for mandatory presence and accepted values.

Key is the name of the query parameter. This is the key that will be used to look up the value in the request.

Value should contain a default value for the query parameter, or a getter function to obtain the value. You are free to use this field as you wish.

MultipleValuesAllowed is a boolean that indicates whether multiple values are allowed for the same key. If this is set to true, the query parameter can have multiple values in the request. If this is set to false, the query parameter should only have one value in the request.

AcceptedValues is a slice of strings that contains the accepted values for the query parameter. If this is not nil, the value of the query parameter in the request must be one of these values. Set it to nil if you do not want to check for accepted values and allow dynamic values.