README
¶
Go REST
Some handy functions for developing JSON-based REST APIs. In particular, it simplifies reading HTTP request bodies, writing HTTP response bodies, and handling errors.
Error handling
You can use errors.Is() to ascertain the type of errors thrown by validation functions, but for the most part, this isn't necessary because the write functions already do that.
Example
package main
import (
"errors"
"math/rand"
"net/http"
"github.com/annybs/go/rest"
)
type Handler struct{}
func (*Handler) ServeHTTP(w http.ResponseWriter, req *http.Request) {
n := rand.Intn(3)
if n == 0 {
rest.WriteResponseJSON(w, http.StatusOK, map[string]string{"status": "OK"})
} else if n == 1 {
rest.WriteErrorJSON(w, errors.New("the original error message is added to data.error"))
} else {
rest.WriteErrorJSON(w, rest.ErrNotFound)
}
}
func main() {
http.ListenAndServe("localhost:8000", &Handler{})
}
Open http://localhost:8000 in your browser and refresh a bunch of times to see the different possible responses.
License
See LICENSE.md
Documentation
¶
Index ¶
- Variables
- func IsAuthenticated(req *http.Request, token string) bool
- func ReadBearerToken(req *http.Request) string
- func ReadRequestJSON(req *http.Request, v any) error
- func WriteError(w http.ResponseWriter, err error) error
- func WriteErrorJSON(w http.ResponseWriter, err error) error
- func WriteResponseJSON(w http.ResponseWriter, statusCode int, data any) error
- type Error
- func (e Error) Error() string
- func (e Error) Is(target error) bool
- func (e Error) WithData(data map[string]interface{}) Error
- func (e Error) WithError(err error) Error
- func (e Error) WithMessage(message string) Error
- func (e Error) WithValue(name string, value any) Error
- func (e Error) Write(w http.ResponseWriter) (int, error)
- func (e Error) WriteJSON(w http.ResponseWriter) error
Constants ¶
This section is empty.
Variables ¶
var ( Err = Error{} ErrMovedPermanently = NewError(http.StatusMovedPermanently, "") // 301 ErrFound = NewError(http.StatusFound, "") // 302 ErrTemporaryRedirect = NewError(http.StatusTemporaryRedirect, "") // 307 ErrPermanentRedirect = NewError(http.StatusPermanentRedirect, "") // 308 ErrBadRequest = NewError(http.StatusBadRequest, "") // 400 ErrPaymentRequired = NewError(http.StatusPaymentRequired, "") // 402 ErrForbidden = NewError(http.StatusForbidden, "") // 403 ErrNotFound = NewError(http.StatusNotFound, "") // 404 ErrMethodNotAllowed = NewError(http.StatusMethodNotAllowed, "") // 405 ErrNotAcceptable = NewError(http.StatusNotAcceptable, "") // 406 ErrInternalServerError = NewError(http.StatusInternalServerError, "") // 500 ErrNotImplemented = NewError(http.StatusNotImplemented, "") // 501 ErrBadGateway = NewError(http.StatusBadGateway, "") // 502 ErrGatewayTimeout = NewError(http.StatusGatewayTimeout, "") // 504 )
REST API error.
Functions ¶
func IsAuthenticated ¶
IsAuthenticated returns true if the bearer token in a request's authorization is equal to a user-defined token. This function always returns true if the user-defined token is empty i.e. no authentication required.
func ReadBearerToken ¶
ReadBearerToken reads the token portion of a bearer token in a request's authorization header. This function returns an empty string if the header is not provided or is not a bearer token.
func ReadRequestJSON ¶
ReadRequestJSON reads the body of an HTTP request into a target reference.
func WriteError ¶
func WriteError(w http.ResponseWriter, err error) error
WriteError writes an error to an HTTP response. If the error is a REST API error, it is written as standard per Error.Write. Otherwise, ErrInternalServerError is written with the given error attached as data.
func WriteErrorJSON ¶
func WriteErrorJSON(w http.ResponseWriter, err error) error
WriteErrorJSON writes an error as JSON to an HTTP response. If the error is a REST API error, it is written as standard per Error.WriteJSON. Otherwise, ErrInternalServerError is written with the given error attached as data.
func WriteResponseJSON ¶
func WriteResponseJSON(w http.ResponseWriter, statusCode int, data any) error
WriteResponseJSON writes an HTTP response as JSON.
Types ¶
type Error ¶
type Error struct {
StatusCode int `json:"-"` // HTTP status code (200, 404, 500 etc.)
Message string `json:"message"` // Status message ("OK", "Not found", "Internal server error" etc.)
Data map[string]interface{} `json:"data,omitempty"` // Optional additional data.
}
Error represents a REST API error. It can be marshaled to JSON with ease and provides a standard format for printing errors and additional data.
func NewError ¶
NewError creates a new REST API error. If the message is empty, the standard text provided by http.StatusText is substituted.
func (Error) Is ¶
Is determines whether the Error is an instance of the target. https://pkg.go.dev/errors#Is
If the target is a REST API error and specifies a status code, this function returns true if the status codes match. If the target is an empty REST API error, this function always returns true.
func (Error) WithError ¶
WithError returns a copy of the HTTP error with the given error added either as the Message, if it empty, or as additional data.
func (Error) WithMessage ¶
WithMessage returns a copy of the HTTP error with the given message.
Source Files