api-responser

README

API Response Package for Go

Darío Chiappello

A lightweight, structured API response handler with built-in error management and support for JSON/XML formats.

Features

• Dual Format Support: JSON & XML responses
• Standardized Error Handling: Central error type registry
• Custom Error Templates: Dynamic error message formatting
• Validation Support: Structured validation error handling
• Extensible Design: Easy to add new response formats

Installation

go get github.com/DarioChiappello/api-responser

Package Structure

1. core.go

Defines interfaces and base response structures:

JsonResponder/XmlResponder interfaces

Common response structs:

BaseResponse: Core success status

SuccessResponse: Successful response container

ErrorDetail: Error metadata structure

ErrorResponse: Error response container

ValidationError: Validation failure detail

2. errors.go

Error management components:

ErrorType: Template for registered errors

ApiError: Custom error implementation

Error registry functions:

RegisterErrorType()

GetErrorType()

RegisterDefaultErrorTypes() (pre-registers common errors)

3. json_responder.go

JSON response implementation:

jsonResponder struct implementing JsonResponder

Methods:

Success(): 200 OK responses

Error(): Error responses

ValidationError(): 400 Bad Request validation errors

4. xml_responder.go

XML response implementation:

xmlResponder struct implementing XmlResponder

Special XML handling:

XML namespace declarations

Proper XML structure enforcement

Usage

Initialization

import "github.com/DarioChiappello/api-responser"


// Register default error types
apiresponse.RegisterDefaultErrorTypes()

// Create responders
jsonResponder := apiresponse.NewJsonResponder()
xmlResponder := apiresponse.NewXmlResponder()

Basic Example

func GetUserHandler(w http.ResponseWriter, r *http.Request) {
    // Success example
    jsonResponder.Success(w, map[string]string{"name": "John Doe"})
    
    // Error example
    err := apiresponse.NewError("not_found", "user_123")
    jsonResponder.Error(w, err)
    
    // Validation error
    validationErrors := []apiresponse.ValidationError{
        {Field: "email", Message: "Invalid format"},
    }
    jsonResponder.ValidationError(w, validationErrors)
}

Custom Error Registration

apiresponse.RegisterErrorType(apiresponse.ErrorType{
    Code:           "payment_failed",
    MessageTemplate: "Payment failed: %v",
    HTTPStatus:     http.StatusBadRequest,
})

Response Examples

JSON Success:

{
    "success": true,
    "data": {
        "user": {
            "name": "John Doe",
            "email": "john@example.com"
        }
    }
}

XML Error:

<response>
    <success>false</success>
    <error>
        <code>not_found</code>
        <message>Resource not found: user_123</message>
        <details>user_123</details>
    </error>
</response>

Run HTML

Validation Error:

{
    "success": false,
    "error": {
        "code": "validation_error",
        "message": "Validation failed",
        "details": [
            {
                "field": "email",
                "message": "Invalid format"
            }
        ]
    }
}

Best Practices

Register Errors Early: Set up error types during initialization

Use Structured Data: Prefer structs over maps for XML responses

Content Negotiation: Select responder based on Accept header

Error Wrapping: Use ApiError for all business logic errors

Validation Consistency: Use ValidationError for input failures

Testing Responses

# Test JSON responses
curl -H "Accept: application/json" http://localhost:8080/api/users

# Test XML responses
curl -H "Accept: application/xml" http://localhost:8080/api/users

License

MIT License - See LICENSE file for details

This README provides:
1. Clear package overview
2. File structure explanation
3. Usage examples
4. Response format samples
5. Best practices
6. Testing instructions

The documentation is structured to help developers quickly understand and implement the package in their projects while maintaining consistency in API responses.