Documentation
¶
Overview ¶
Package problem provides utilities for constructing and handling error responses in accordance with RFC 9457 (Problem Details for HTTP APIs).
This package offers a structured way to create detailed error responses. Additionally, it provides helper functions for common error scenarios.
Index ¶
- Constants
- Variables
- type DetailedError
- func BadParameters(r *http.Request, parameters ...Parameter) *DetailedError
- func BadRequest(r *http.Request) *DetailedError
- func BusinessRuleViolation(r *http.Request, properties ...Property) *DetailedError
- func ConstraintViolation(r *http.Request, properties ...Property) *DetailedError
- func Forbidden(r *http.Request) *DetailedError
- func NotFound(r *http.Request) *DetailedError
- func ResourceExists(r *http.Request) *DetailedError
- func ServerError(r *http.Request) *DetailedError
- func Unauthorized(r *http.Request) *DetailedError
- func (d *DetailedError) Error() string
- func (d *DetailedError) MarshalJSON() ([]byte, error)
- func (d *DetailedError) MustMarshalJSON() []byte
- func (d *DetailedError) MustMarshalJSONString() string
- func (d *DetailedError) UnmarshalJSON(data []byte) error
- func (d *DetailedError) WithDetail(detail string) *DetailedError
- func (d *DetailedError) WithExtension(k string, v any) *DetailedError
- type Parameter
- type ParameterType
- type Property
Constants ¶
const ( // DefaultErrorDocumentationLocation is the default URL pointing to the documentation // for Problem Details format. It can be overridden using the ErrorDocumentationLocation var. DefaultErrorDocumentationLocation = "https://github.com/nickbryan/httputil/blob/main/docs/problems/" )
Variables ¶
var ErrorDocumentationLocation = DefaultErrorDocumentationLocation //nolint:gochecknoglobals // Global var improves API without degrading user experience.
ErrorDocumentationLocation specifies the URL for the documentation of the Problem Details format. This variable can be customized to point to your own API documentation or a different reference.
Functions ¶
This section is empty.
Types ¶
type DetailedError ¶
type DetailedError struct {
// Type is a URI reference that identifies the specific problem.
Type string `json:"type"`
// Title is a short, human-readable summary of the problem type.
Title string `json:"title"`
// Detail is a human-readable explanation specific to the occurrence of the problem.
Detail string `json:"detail"`
// Status is the HTTP status code associated with the problem.
Status int `json:"status"`
// Code is the domain-specific error code associated with the problem.
Code string `json:"code"`
// Instance is a URI reference that identifies the specific occurrence of the problem.
Instance string `json:"instance"`
// ExtensionMembers is a key-value map for vendor-specific extension members.
ExtensionMembers map[string]any `json:"-"` // See DetailedError.UnmarshalJSON for how this is mapped.
}
DetailedError encapsulates the fields required to respond with an error in accordance with RFC 9457 (Problem Details for HTTP APIs).
func BadParameters ¶
func BadParameters(r *http.Request, parameters ...Parameter) *DetailedError
BadParameters creates a DetailedError for invalid or malformed request parameters. This function is used when the request contains query, header, or path parameters that do not meet the expected requirements. You may provide details about the specific violations using the parameters parameter. Each parameter in the parameters slice holds information about the invalid parameter, including its name, type, and a description of the issue.
func BadRequest ¶
func BadRequest(r *http.Request) *DetailedError
BadRequest creates a DetailedError for bad request errors.
func BusinessRuleViolation ¶
func BusinessRuleViolation(r *http.Request, properties ...Property) *DetailedError
BusinessRuleViolation creates a DetailedError for business rule violation errors. This function is used when a request violates one or more business rules set by the application. You may pass additional details about the specific violations using the properties parameter.
func ConstraintViolation ¶
func ConstraintViolation(r *http.Request, properties ...Property) *DetailedError
ConstraintViolation creates a DetailedError for constraint validation errors. This function is used when the request data violates one or more validation constraints. You may provide additional details about the specific violations using the properties parameter. If no properties are provided, the violations field will be an empty array.
func Forbidden ¶
func Forbidden(r *http.Request) *DetailedError
Forbidden creates a DetailedError for forbidden errors.
func NotFound ¶
func NotFound(r *http.Request) *DetailedError
NotFound creates a DetailedError for not found errors.
func ResourceExists ¶
func ResourceExists(r *http.Request) *DetailedError
ResourceExists creates a DetailedError for duplicate resource errors.
func ServerError ¶
func ServerError(r *http.Request) *DetailedError
ServerError creates a DetailedError for internal server errors.
func Unauthorized ¶
func Unauthorized(r *http.Request) *DetailedError
Unauthorized creates a DetailedError for unauthorized errors.
func (*DetailedError) Error ¶
func (d *DetailedError) Error() string
Error implements the `error` interface, allowing DetailedError objects to be used as errors.
func (*DetailedError) MarshalJSON ¶
func (d *DetailedError) MarshalJSON() ([]byte, error)
MarshalJSON implements the `json.Marshaler` interface for DetailedError. It marshals the DetailedError object into a JSON byte slice.
func (*DetailedError) MustMarshalJSON ¶
func (d *DetailedError) MustMarshalJSON() []byte
MustMarshalJSON marshals the DetailedError into JSON and panics if an error occurs during the marshaling process. This is useful for testing the comparison of error responses.
func (*DetailedError) MustMarshalJSONString ¶
func (d *DetailedError) MustMarshalJSONString() string
MustMarshalJSONString converts the DetailedError to a JSON string and panics if an error occurs during marshaling.
func (*DetailedError) UnmarshalJSON ¶
func (d *DetailedError) UnmarshalJSON(data []byte) error
UnmarshalJSON implements the `json.Unmarshaler` interface for DetailedError, handling known and unknown fields gracefully.
func (*DetailedError) WithDetail ¶
func (d *DetailedError) WithDetail(detail string) *DetailedError
WithDetail creates a new DetailedError instance with the provided detail message. It returns a copy of the original DetailedError with the updated Detail field.
func (*DetailedError) WithExtension ¶
func (d *DetailedError) WithExtension(k string, v any) *DetailedError
WithExtension creates a new DetailedError instance with an added or updated extension member. It returns a copy of the original DetailedError with the specified extension member added or updated. If the original DetailedError has no ExtensionMembers, a new map is created. Returns a new DetailedError instance with the added or updated extension member. The original DetailedError is not modified.
type Parameter ¶
type Parameter struct {
Parameter string `json:"parameter"`
Detail string `json:"detail"`
Type ParameterType `json:"type"`
}
Parameter represents a specific parameter that caused an error during request validation. It provides details about the error, the parameter name, and its type (query, header, path).
type ParameterType ¶
type ParameterType string
ParameterType defines the type of the parameter that caused an error. It is used to classify parameters into query parameters, header parameters, or path parameters and to provide more context about the specific issue.
const ( // ParameterTypeQuery indicates that the parameter error is related to a query // parameter. Query parameters are typically part of the URL and are used to // pass data to the server. ParameterTypeQuery ParameterType = "query" // ParameterTypeHeader indicates that the parameter error is related to a header // parameter. Header parameters are sent as part of the HTTP request headers and // provide metadata about the request or additional information required by the // server. ParameterTypeHeader ParameterType = "header" // ParameterTypePath indicates that the parameter error is related to a path // parameter. Path parameters are used in the URL path and typically represent a // resource identifier or dynamic data. ParameterTypePath ParameterType = "path" )
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package problemtest provides utilities for creating and testing problems.
|
Package problemtest provides utilities for creating and testing problems. |