api

README

API

Concise library for generating API responses in JSON format

Shortcut methods

• Error(msg string)
• ErrorWithData(msg string, data []interface)
• Forbidden(msg string)
• Success(msg string)
• SuccessWithData(msg string, data []interface)
• Unauthenticated(msg string)
• Unauthorized(msg string)

Example

// return error response
api.Respond(w, r, api.Error("api key is required"))

// return error response with HTTP status sode
api.RespondWithStatusCode(w, r, api.Error("endpoint not found"), http.StatusNotFound)

// return success response with data payload
api.Respond(w, r, api.SuccessWithData("success", map[string]interface{}{
  "key1": "value1",
  "key2": "value1",
  "key3": "value1",
}))

Custom responses

api.Respond(w, r, api.Response{
  Status:  "custom_status",
  Message: "message",
  Data: map[string]interface{}{
    "key1": "value1",
    "key2": "value1",
    "key3": "value1",
  },
})

What is the Difference Between Unauthenticated, Unauthorized and Forbidden?

1. Unauthenticated: This is the most fundamental level of access control. If a user or system cannot be verified as a legitimate entity, it will be denied access to any resource.
2. Unauthorized: Once a user or system has been authenticated, it must also be authorized to access a particular resource. If it lacks the necessary permissions, it will be denied access.
3. Forbidden: This is the highest level of access control. Even if a user or system is both authenticated and authorized, it may still be denied access to a resource if there are specific conditions or rules in place that prohibit access.

In summary:

Unauthenticated -> Unauthorized -> Forbidden

This order reflects the increasing levels of verification and permission required to access a resource.

However in REST context, these are represented with ambiguous status codes:

• Unauthenticated is represented by 401 Unauthorized: This indicates that the client needs to authenticate itself with the server. Typically, this involves providing credentials like a username and password.

• Unauthorized & Forbidden are both represented by 403 Forbidden: This means the server understood the request but refuses to fulfill it. This could be due to a lack of necessary permissions or a policy restriction.

Documentation

Index

• Constants
• func Respond(w http.ResponseWriter, r *http.Request, resp Response)
• func RespondWithStatusCode(w http.ResponseWriter, r *http.Request, resp Response, status int)
• type Response
  • func Error(message string) Response
  • func ErrorWithData(message string, data map[string]any) Response
  • func Forbidden(message string) Response
  • func ForbiddenWithData(message string, data map[string]any) Response
  • func Success(message string) Response
  • func SuccessWithData(message string, data map[string]any) Response
  • func Unauthenticated(message string) Response
  • func UnauthenticatedWithData(message string, data map[string]any) Response
  • func Unauthorized(message string) Response
  • func UnauthorizedWithData(message string, data map[string]any) Response
  • func (r Response) ToString() string

Constants

const TYPE_ERROR = "error"

const TYPE_FORBIDDEN = "forbidden"

const TYPE_SUCCESS = "success"

const TYPE_UNAUTHENTICATED = "unauthenticated"

const TYPE_UNAUTHORIZED = "unauthorized"

Functions

func Respond

func Respond(w http.ResponseWriter, r *http.Request, resp Response)

Respond writes a JSON or JSONP response

func RespondWithStatusCode

func RespondWithStatusCode(w http.ResponseWriter, r *http.Request, resp Response, status int)

Respond writes a JSON or JSONP response with a status code

Types

type Response

type Response struct {
	Status  string                 `json:"status"`
	Message string                 `json:"message"`
	Data    map[string]interface{} `json:"data"`
}

Response defines an response for the API

func Error

func Error(message string) Response

Error returns an error message

func ErrorWithData

func ErrorWithData(message string, data map[string]any) Response

ErrorWithData returns an error message with data

func Forbidden

func Forbidden(message string) Response

Forbidden returns an forbidden message, user is authenticated but insufficient permissions

func ForbiddenWithData

func ForbiddenWithData(message string, data map[string]any) Response

ForbiddenWithData returns a forbidden message with data

func Success

func Success(message string) Response

Success returns a success message

func SuccessWithData

func SuccessWithData(message string, data map[string]any) Response

SuccessWithData returns a success message with data

func Unauthenticated

func Unauthenticated(message string) Response

Unauthenticated returns an unauthenticated message, user is not known (not authenticated)

func UnauthenticatedWithData

func UnauthenticatedWithData(message string, data map[string]any) Response

Unauthenticated returns an unauthenticated message, user is not known (not authenticated)

func Unauthorized

func Unauthorized(message string) Response

Unauthorized returns an unauthorized message, user is known but not unauthorized to do the action

func UnauthorizedWithData

func UnauthorizedWithData(message string, data map[string]any) Response

Unauthorized returns an unauthorized message, user is known but not unauthorized to do the action

func (Response) ToString

func (r Response) ToString() string