responsehelper

README

Response Helper

This is a simple utility that helps to standardize api responses across the application.

Installation

go get github.com/aruncs31s/responsehelper

import "github.com/aruncs31s/responsehelper"

Usage

I suggest you that you include this in your handler constructor like the following

type Handler struct {
    responseHelper responsehelper.ResponseHelper
}
func NewHandler() *Handler {
    return &Handler{
        responseHelper: responsehelper.NewResponseHelper(),
    }
}

Then you can use it in your handler methods like the following

h.responseHelper.Success(c, data)

{
    "success": true,
    "data": {
    // response data here
    },
    "meta": "2025-10-01T00:00:00Z"
}

Example used with Gin framework

func (h *userHandler) Login(c *gin.Context) {
	var loginData dto.LoginRequest
	if err := c.ShouldBindJSON(&loginData); err != nil {
		h.responseHelper.BadRequest(c, utils.ErrBadRequest.Error(), utils.ErrDetailBadRequestJSONPayload.Error())
		return
	}

	token, err := h.userService.Login(loginData.Email, loginData.Password)
	if err != nil {
		reaction := utils.NewReaction(err)
		if strings.Contains(err.Error(), utils.ErrNotFound.Error()) {
			h.responseHelper.Unauthorized(c, utils.ErrEmailorPasswordEmpty.Error())
			return
		}
		h.responseHelper.InternalError(c, reaction.Reaction(), err)
		return
	}
	data := map[string]string{"token": token}
	
	h.responseHelper.Success(c, data)

Features

Comes with intellisense support for VSCode and other IDEs.

Available Response Methods

Success(c *gin.Context, data interface{})

Sends a 200 OK response with the provided data.

SuccessWithPagination(c *gin.Context, data interface{}, meta interface{})

Sends a 200 OK response with data and pagination metadata.

BadRequest(c *gin.Context, message string, details string)

Sends a 400 Bad Request response with custom error message and details.

Unauthorized(c *gin.Context, message string)

Sends a 401 Unauthorized response.

NotFound(c *gin.Context, message string)

Sends a 404 Not Found response.

Conflict(c *gin.Context, message string, err error)

Sends a 409 Conflict response for resource conflicts.

h.responseHelper.Conflict(c, "Resource conflict", err)

Response:

{
    "success": false,
    "error": {
        "code": 409,
        "status": "CONFLICT",
        "message": "Resource conflict",
        "details": "Error details here"
    }
}

AlreadyExists(c *gin.Context, resource string, err error)

Sends a 409 Conflict response indicating that a resource already exists. This is a convenience method for the common case where a resource creation fails because the resource already exists.

h.responseHelper.AlreadyExists(c, "User", err)

Response:

{
    "success": false,
    "error": {
        "code": 409,
        "status": "CONFLICT",
        "message": "User already exists",
        "details": "Error details here"
    }
}

InternalError(c *gin.Context, message string, err error)

Sends a 500 Internal Server Error response.

Documentation

Index

• type ResponseHelper
  • func NewResponseHelper() ResponseHelper

Types

type ResponseHelper

type ResponseHelper interface {
	// BadRequest sends a 400 Bad Request response
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - message: A brief message describing the error.
	//   - details: Additional details about the error.
	//
	// Example:
	//  responseHelper.BadRequest(c, "Invalid input", "The 'name' field is required.")
	//
	// Example Response Body:
	// {
	//	"success": false,
	//	"error": {
	//		"code":    400,
	//		"status":  "BAD_REQUEST",
	//		"message": "Invalid input",
	//		"details": "The 'name' field is required."
	//	}
	// }
	BadRequest(c *gin.Context, message string, details string)

	// AlreadyExists sends a 409 Conflict response indicating resource already exists
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - resource: The name of the resource that already exists.
	//   - err: The error that occurred.
	//
	// Example:
	//  responseHelper.AlreadyExists(c, "User", err)
	//
	// Example Response Body:
	// {
	//	"success": false,
	//	"error": {
	//		"code":    409,
	//		"status":  "CONFLICT",
	//		"message": "User already exists",
	//		"details": "Error details here"
	//	}
	// }
	AlreadyExists(c *gin.Context, resource string, err error)

	// Conflict sends a 409 Conflict response
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - message: A brief message describing the error.
	//   - err: The error that occurred.
	//
	// Example:
	//  h.responseHelper.Conflict(c, "Resource conflict", err)
	//
	// Example Response Body:
	// {
	//	"success": false,
	//	"error": {
	//		"code":    409,
	//		"status":  "CONFLICT",
	//		"message": "Resource conflict",
	//		"details": "Error details here"
	//	}
	// }
	Conflict(c *gin.Context, message string, err error)
	// NotFound sends a 404 Not Found response
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - message: A brief message describing the error.
	//
	// Example:
	//  h.responseHelper.NotFound(c, "Resource not found")
	//
	// Example Response Body:
	// {
	//	"success": false,
	//	"error": {
	//		"code":    404,
	//		"status":  "NOT_FOUND",
	//		"message": "Resource not found"
	//	}
	// }
	NotFound(c *gin.Context, message string)

	// Unauthorized sends a 401 Unauthorized response
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - message: A brief message describing the error.
	//
	// Example:
	// h.responseHelper.Unauthorized(c, "Unauthorized access")
	//
	// Example Response Body:
	// {
	//	"success": false,
	//	"error": {
	//		"code":    401,
	//		"status":  "UNAUTHORIZED",
	//		"message": "Unauthorized access"
	//	}
	// }
	Unauthorized(c *gin.Context, message string)

	// InternalError sends a 500 Internal Server Error response
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - message: A brief message describing the error.
	//   - err: The error that occurred.
	//
	// Example:
	//  h.responseHelper.InternalError(c, "An unexpected error occurred", err)
	//
	// Example Response Body:
	// {
	//	"success": false,
	//	"error": {
	//		"code":    500,
	//		"status":  "INTERNAL_SERVER_ERROR",
	//		"message": "An unexpected error occurred",
	//		"details": "Error details here"
	//	}
	// }
	InternalError(c *gin.Context, message string, err error)

	// Success sends a 200 OK response
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - data: The data to include in the response.
	//
	// Example:
	//  h.responseHelper.Success(c, data)
	//
	// Example Response Body:
	// {
	//	"success": true,
	//	"data": {
	//		// response data here
	//	},
	//	"meta": "2023-01-01T00:00:00Z"
	// }
	Success(c *gin.Context, data interface{})

	// SuccessWithPagination sends a 200 OK response with pagination metadata
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - data: The data to include in the response.
	//   - meta: The pagination metadata.
	//
	// Example:
	//  h.responseHelper.SuccessWithPagination(c, data, meta)
	//
	// Example Response Body:
	// {
	//	"success": true,
	//	"data": {
	//		// response data here
	//	},
	//	"pagination": {
	//		"currentPage": 3,
	//		"pageSize": 10,
	//		"totalPages": 3,
	//		"totalRecords": 27
	//	}
	// }
	SuccessWithPagination(c *gin.Context, data interface{}, meta interface{})

	// Created sends a 201 Created response
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - data: The data to include in the response.
	//
	// Example:
	//  responseHelper.Created(c, data)
	//
	// Example Response Body:
	// {
	//	"success": true,
	//	"data": {
	//		// response data here
	//	},
	//	"meta": "2023-01-01T00:00:00Z"
	// }
	Created(c *gin.Context, data interface{})

	// Deleted sends a 204 No Content response
	//
	// Parameters:
	//   - c: The Gin context to send the response to.
	//   - message: what you have deleted eg: qualification
	//
	// Example:
	//  responseHelper.Deleted(c, "qualification")
	//
	// Example Response Body:
	// {
	//	"success": true,
	//	"message": "qualification deleted successfully",
	//	"meta": "2023-01-01T00:00:00Z"
	// }
	Deleted(c *gin.Context, message string)
}

These are the possible responses from the API.

func NewResponseHelper

func NewResponseHelper() ResponseHelper