apieasy

README

APIEasy

APIEasy is a lightweight web framework for Go that simplifies the creation and handling of HTTP requests. It provides a convenient router and context for building robust web applications with minimal boilerplate code.

Features

1. HTTP Request Handling: Easily define routes and handle HTTP methods.
2. JSON Response: Simplified methods for returning JSON responses with customizable status codes.
3. Flexible Routing: Supports GET, POST, PUT, DELETE, and other HTTP methods.
4. Middleware Support: Extendable middleware for additional request processing.
5. Error Handling: Built-in mechanisms for handling errors and status codes.

Installation

To use APIEasy in your Go project, follow these steps:

1. Install Go (if not already installed): https://golang.org/doc/install

2. Create a new Go module (if not already created):

   go mod init myapp
   

3. Install APIEasy:

   go get github.com/Webblurt/apieasy
   

Example Usage Here's a basic example of setting up and running an HTTP server using APIEasy:

```golang
package main

import (
    "github.com/Webblurt/apieasy"
)

func main() {
    router := apieasy.NewRouter(":8080")

    router.Handle("GET", "/hello", func(ctx *apieasy.Context) {
        ctx.SetStatus(apieasy.OK, "Hello, World!", nil)
    })

    router.Handle("POST", "/api/data", func(ctx *apieasy.Context) {
        data := struct {
            Message string `json:"message"`
        }{
            Message: "Data received successfully",
        }
        ctx.JSON(apieasy.OK, data)
    })

    if err := router.Run(); err != nil {
        panic(err)
    }
}
```

Routing

Routes and handlers are added using the Handle method of the router. Handlers receive a Context object that contains information about the current request and methods to set the response status and message.

Additional Information

1. APIEasy supports custom HTTP statuses and provides a convenient interface for request handling.
2. Use SetStatus to set the response status and message within a handler.
3. Visit the Go documentation for more information on the standard library.

Contributing and Issue Reporting

If you have suggestions for improvements or find a bug, please open an issue on GitHub or submit a pull request. Contributions are welcome!

License

APIEasy is licensed under the MIT License. See the LICENSE file for more information.

Documentation

Index

• Variables
• func AddURLParams(rawURL string, params map[string]string) (string, error)
• func ApiEasyCorsMiddlewareDefault(next http.Handler) http.Handler
• func NewHTTPClient(config HTTPClientConfig) *http.Client
• func SetCorsMiddleware(allowedOrigins, allowedMethods, allowedHeaders string) func(http.Handler) http.Handler
• type APIResponse
  • func SendRequest(client *http.Client, method, rawURL string, headers map[string]string, ...) (*APIResponse, error)
• type Context
  • func NewContext(w http.ResponseWriter, req *http.Request) *Context
  • func (c *Context) JSON(status StatusCode, data interface{})
  • func (c *Context) SetStatus(code StatusCode, message interface{}, err error)
• type HTTPClientConfig
• type HTTPHandlerFunc
• type HandlerFunc
• type MiddlewareFunc
• type ResponseWriter
• type Router
  • func NewRouter(addr ...string) *Router
  • func (r *Router) AddMiddleware(mw func(http.Handler) http.Handler)
  • func (r *Router) Handle(method string, pattern string, handler HandlerFunc)
  • func (r *Router) Run() error
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) Use(mw MiddlewareFunc)
• type Routes
• type Status
• type StatusCode

Variables

var (
	Success = struct {
		Default                   StatusCode
		OK                        StatusCode
		Created                   StatusCode
		Accepted                  StatusCode
		NonAuthritativeInformaton StatusCode
		NoContent                 StatusCode
		ResetContent              StatusCode
		PartialContent            StatusCode
		MultiStatus               StatusCode
		AlreadyReported           StatusCode
		IMUsed                    StatusCode
	}{
		Default:                   OK,
		OK:                        OK,
		Created:                   Created,
		Accepted:                  Accepted,
		NonAuthritativeInformaton: NonAuthritativeInformaton,
		NoContent:                 NoContent,
		ResetContent:              ResetContent,
		PartialContent:            PartialContent,
		MultiStatus:               MultiStatus,
		AlreadyReported:           AlreadyReported,
		IMUsed:                    IMUsed,
	}

	Redirection = struct {
		Default           StatusCode
		MultipleChoices   StatusCode
		MovedPermanently  StatusCode
		Found             StatusCode
		SeeOther          StatusCode
		NotModified       StatusCode
		UseProxy          StatusCode
		TemporaryRedirect StatusCode
		PermanentRedirect StatusCode
	}{
		Default:           MovedPermanently,
		MultipleChoices:   MultipleChoices,
		MovedPermanently:  MovedPermanently,
		Found:             Found,
		SeeOther:          SeeOther,
		NotModified:       NotModified,
		UseProxy:          UseProxy,
		TemporaryRedirect: TemporaryRedirect,
		PermanentRedirect: PermanentRedirect,
	}

	ClientError = struct {
		Default                      StatusCode
		BadRequest                   StatusCode
		Unauthorized                 StatusCode
		PaymentRequired              StatusCode
		Forbidden                    StatusCode
		NotFound                     StatusCode
		MethodNotAllowed             StatusCode
		NotAcceptable                StatusCode
		ProxyAuthRequired            StatusCode
		RequestTimeout               StatusCode
		Conflict                     StatusCode
		Gone                         StatusCode
		LengthRequired               StatusCode
		PreconditionFailed           StatusCode
		RequestEntityTooLarge        StatusCode
		RequestURITooLong            StatusCode
		UnsupportedMediaType         StatusCode
		RequestedRangeNotSatisfiable StatusCode
		ExpectationFailed            StatusCode
		Teapot                       StatusCode
		MisdirectedRequest           StatusCode
		UnprocessableEntity          StatusCode
		Locked                       StatusCode
		FailedDependency             StatusCode
		UpgradeRequired              StatusCode
		PreconditionRequired         StatusCode
		TooManyRequests              StatusCode
		RequestHeaderFieldsTooLarge  StatusCode
		UnavailableForLegalReasons   StatusCode
		ClientClosedRequest          StatusCode
	}{
		Default:                      BadRequest,
		BadRequest:                   BadRequest,
		Unauthorized:                 Unauthorized,
		PaymentRequired:              PaymentRequired,
		Forbidden:                    Forbidden,
		NotFound:                     NotFound,
		MethodNotAllowed:             MethodNotAllowed,
		NotAcceptable:                NotAcceptable,
		ProxyAuthRequired:            ProxyAuthRequired,
		RequestTimeout:               RequestTimeout,
		Conflict:                     Conflict,
		Gone:                         Gone,
		LengthRequired:               LengthRequired,
		PreconditionFailed:           PreconditionFailed,
		RequestEntityTooLarge:        RequestEntityTooLarge,
		RequestURITooLong:            RequestURITooLong,
		UnsupportedMediaType:         UnsupportedMediaType,
		RequestedRangeNotSatisfiable: RequestedRangeNotSatisfiable,
		ExpectationFailed:            ExpectationFailed,
		Teapot:                       Teapot,
		MisdirectedRequest:           MisdirectedRequest,
		UnprocessableEntity:          UnprocessableEntity,
		Locked:                       Locked,
		FailedDependency:             FailedDependency,
		UpgradeRequired:              UpgradeRequired,
		PreconditionRequired:         PreconditionRequired,
		TooManyRequests:              TooManyRequests,
		RequestHeaderFieldsTooLarge:  RequestHeaderFieldsTooLarge,
		UnavailableForLegalReasons:   UnavailableForLegalReasons,
		ClientClosedRequest:          ClientClosedRequest,
	}

	ServerError = struct {
		Default                       StatusCode
		InternalServerError           StatusCode
		NotImplemented                StatusCode
		BadGateway                    StatusCode
		ServiceUnavailable            StatusCode
		GatewayTimeout                StatusCode
		HttpVersionNotSupported       StatusCode
		VariantAlsoNegotiates         StatusCode
		InsufficientStorage           StatusCode
		LoopDetected                  StatusCode
		NotExtended                   StatusCode
		NetworkAuthenticationRequired StatusCode
		NetworkConnectTimeout         StatusCode
	}{
		Default:                       InternalServerError,
		InternalServerError:           InternalServerError,
		NotImplemented:                NotImplemented,
		BadGateway:                    BadGateway,
		ServiceUnavailable:            ServiceUnavailable,
		GatewayTimeout:                GatewayTimeout,
		HttpVersionNotSupported:       HttpVersionNotSupported,
		VariantAlsoNegotiates:         VariantAlsoNegotiates,
		InsufficientStorage:           InsufficientStorage,
		LoopDetected:                  LoopDetected,
		NotExtended:                   NotExtended,
		NetworkAuthenticationRequired: NetworkAuthenticationRequired,
		NetworkConnectTimeout:         NetworkConnectTimeout,
	}
)

var StatusText = map[StatusCode]string{

	OK:                        "OK",
	Created:                   "Created",
	Accepted:                  "Accepted",
	NonAuthritativeInformaton: "Non Authritative Informaton",
	NoContent:                 "No Content",
	ResetContent:              "Reset Content",
	PartialContent:            "Partial Content",
	MultiStatus:               "Multi Status",
	AlreadyReported:           "Already Reported",
	IMUsed:                    "IM Used",

	MultipleChoices:   "Multiple Choices",
	MovedPermanently:  "Moved Permanently",
	Found:             "Found",
	SeeOther:          "See Other",
	NotModified:       "Not Modified",
	UseProxy:          "Use Proxy",
	TemporaryRedirect: "Temporary Redirect",
	PermanentRedirect: "Permanent Redirect",

	BadRequest:                   "Bad Request",
	Unauthorized:                 "Unauthorized",
	PaymentRequired:              "Payment Required",
	Forbidden:                    "Forbidden",
	NotFound:                     "Not Found",
	MethodNotAllowed:             "Method Not Allowed",
	NotAcceptable:                "Not Acceptable",
	ProxyAuthRequired:            "Proxy Auth Required",
	RequestTimeout:               "Request Timeout",
	Conflict:                     "Conflict",
	Gone:                         "Gone",
	LengthRequired:               "Length Required",
	PreconditionFailed:           "Precondition Failed",
	RequestEntityTooLarge:        "Request Entity Too Large",
	RequestURITooLong:            "Request URI Too Long",
	UnsupportedMediaType:         "Unsupported Media Type",
	RequestedRangeNotSatisfiable: "Requested Range Not Satisfiable",
	ExpectationFailed:            "Expectation Failed",
	Teapot:                       "Teapot",
	MisdirectedRequest:           "Misdirected Request",
	UnprocessableEntity:          "Unprocessable Entity",
	Locked:                       "Locked",
	FailedDependency:             "Failed Dependency",
	UpgradeRequired:              "Upgrade Required",
	PreconditionRequired:         "Precondition Required",
	TooManyRequests:              "Too Many Requests",
	RequestHeaderFieldsTooLarge:  "Request Header Fields Too Large",
	UnavailableForLegalReasons:   "Unavailable For Legal Reasons",
	ClientClosedRequest:          "Client Closed Request",

	InternalServerError:           "Internal Server Error",
	NotImplemented:                "Not Implemented",
	BadGateway:                    "Bad Gateway",
	ServiceUnavailable:            "Service Unavailable",
	GatewayTimeout:                "Gateway Timeout",
	HttpVersionNotSupported:       "HTTP Version Not Supported",
	VariantAlsoNegotiates:         "Variant Also Negotiates",
	InsufficientStorage:           "Insufficient Storage",
	LoopDetected:                  "Loop Detected",
	NotExtended:                   "Not Extended",
	NetworkAuthenticationRequired: "Network Authentication Required",
	NetworkConnectTimeout:         "Network Connect Timeout",
}

Functions

func AddURLParams

func AddURLParams(rawURL string, params map[string]string) (string, error)

AddURLParams adds URL parameters to the given URL

func ApiEasyCorsMiddlewareDefault

func ApiEasyCorsMiddlewareDefault(next http.Handler) http.Handler

func NewHTTPClient

func NewHTTPClient(config HTTPClientConfig) *http.Client

NewHTTPClient creates a new HTTP client with the given configuration

func SetCorsMiddleware

func SetCorsMiddleware(allowedOrigins, allowedMethods, allowedHeaders string) func(http.Handler) http.Handler

Types

type APIResponse

type APIResponse struct {
	StatusCode int
	Headers    http.Header
	Body       string
}

func SendRequest

func SendRequest(client *http.Client, method, rawURL string, headers map[string]string, body io.Reader) (*APIResponse, error)

SendRequest sends an HTTP request with optional headers and body, and returns the complete response or an error

type Context

type Context struct {
	Writer         http.ResponseWriter
	Request        *http.Request
	ResponseStatus Status
	Status         StatusCode
	Message        interface{}
}

func NewContext

func NewContext(w http.ResponseWriter, req *http.Request) *Context

func (*Context) JSON

func (c *Context) JSON(status StatusCode, data interface{})

func (*Context) SetStatus

func (c *Context) SetStatus(code StatusCode, message interface{}, err error)

type HTTPClientConfig

type HTTPClientConfig struct {
	Timeout       time.Duration
	SkipTLSVerify bool
}

HTTPClientConfig defines the configuration for the HTTP client

type HTTPHandlerFunc

type HTTPHandlerFunc func(ResponseWriter, *http.Request)

type HandlerFunc

type HandlerFunc func(*Context)

type MiddlewareFunc

type MiddlewareFunc func(http.Handler) http.Handler

type ResponseWriter

type ResponseWriter interface {
	WriteHeader(statusCode int)
	Write([]byte) (int, error)
}

type Router

type Router struct {
	// contains filtered or unexported fields
}

func NewRouter

func NewRouter(addr ...string) *Router

func (*Router) AddMiddleware

func (r *Router) AddMiddleware(mw func(http.Handler) http.Handler)

func (*Router) Handle

func (r *Router) Handle(method string, pattern string, handler HandlerFunc)

func (*Router) Run

func (r *Router) Run() error

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

func (*Router) Use

func (r *Router) Use(mw MiddlewareFunc)

type Routes

type Routes interface {
	ServeHTTP(ResponseWriter, *http.Request)
	Get(string, HTTPHandlerFunc) Router
	Post(string, HTTPHandlerFunc) Router
	Put(string, HTTPHandlerFunc) Router
	Delete(string, HTTPHandlerFunc) Router
	Options(string, HTTPHandlerFunc) Router
	Head(string, HTTPHandlerFunc) Router
	Patch(string, HTTPHandlerFunc) Router
	Run() error
	Handle(method, pattern string, handler HandlerFunc)
}

type Status

type Status struct {
	Code    StatusCode
	Message interface{}
}

type StatusCode

type StatusCode int

const (
	// 2xx Success
	OK                        StatusCode = 200
	Created                   StatusCode = 201
	Accepted                  StatusCode = 202
	NonAuthritativeInformaton StatusCode = 203
	NoContent                 StatusCode = 204
	ResetContent              StatusCode = 205
	PartialContent            StatusCode = 206
	MultiStatus               StatusCode = 207
	AlreadyReported           StatusCode = 208
	IMUsed                    StatusCode = 226

	MultipleChoices   StatusCode = 300
	MovedPermanently  StatusCode = 301
	Found             StatusCode = 302
	SeeOther          StatusCode = 303
	NotModified       StatusCode = 304
	UseProxy          StatusCode = 305
	TemporaryRedirect StatusCode = 307
	PermanentRedirect StatusCode = 308

	BadRequest                   StatusCode = 400
	Unauthorized                 StatusCode = 401
	PaymentRequired              StatusCode = 402
	Forbidden                    StatusCode = 403
	NotFound                     StatusCode = 404
	MethodNotAllowed             StatusCode = 405
	NotAcceptable                StatusCode = 406
	ProxyAuthRequired            StatusCode = 407
	RequestTimeout               StatusCode = 408
	Conflict                     StatusCode = 409
	Gone                         StatusCode = 410
	LengthRequired               StatusCode = 411
	PreconditionFailed           StatusCode = 412
	RequestEntityTooLarge        StatusCode = 413
	RequestURITooLong            StatusCode = 414
	UnsupportedMediaType         StatusCode = 415
	RequestedRangeNotSatisfiable StatusCode = 416
	ExpectationFailed            StatusCode = 417
	Teapot                       StatusCode = 418
	MisdirectedRequest           StatusCode = 421
	UnprocessableEntity          StatusCode = 422
	Locked                       StatusCode = 423
	FailedDependency             StatusCode = 424
	UpgradeRequired              StatusCode = 426
	PreconditionRequired         StatusCode = 428
	TooManyRequests              StatusCode = 429
	RequestHeaderFieldsTooLarge  StatusCode = 431
	UnavailableForLegalReasons   StatusCode = 451
	ClientClosedRequest          StatusCode = 499

	InternalServerError           StatusCode = 500
	NotImplemented                StatusCode = 501
	BadGateway                    StatusCode = 502
	ServiceUnavailable            StatusCode = 503
	GatewayTimeout                StatusCode = 504
	HttpVersionNotSupported       StatusCode = 505
	VariantAlsoNegotiates         StatusCode = 506
	InsufficientStorage           StatusCode = 507
	LoopDetected                  StatusCode = 508
	NotExtended                   StatusCode = 510
	NetworkAuthenticationRequired StatusCode = 511
	NetworkConnectTimeout         StatusCode = 599
)