requiem

README

requiem

Controller-based REST API server container for Golang with Postgres support

• Uses GORM for DB interaction with Postgres
• Uses Gorilla Mux for routing
• Uses logmatic for nice server logs
• Default port is 8080
• Default base path is /api

Documentation here: https://godoc.org/github.com/borderstech/requiem

Example Usage

Without DB

s := requiem.NewServer(... controllers)
s.Start()

With DB

s := requiem.NewServer(... controllers)
s.EnableDB = true
s.Start()

Change port or base path

s := requiem.NewServer(... controllers)
s.Port = 9090
s.BasePath = "/rest"
s.Start()

HttpController example

type MyController struct {
    DB *gorm.DB
}

type Response struct {
    Message string
}

type CreateRequest struct {
    SomeValue string
}

func (c MyController) getStuff(ctx requiem.HTTPContext) {
    m := Response{Message: "Hello, world!"}
    ctx.SendJSON(res)
}

func (c MyController) createStuff(ctx requiem.HTTPContext) {
    m := ctx.Body.(*CreateRequest)
    fmt.Println("Value: %s", m.SomeValue)
    ctx.SendStatus(Http.StatusNoContent)
}

func (c MyController) Load(router *requiem.Router) {
    c.DB = router.DB
    r := router.NewAPIRouter("/stuff")
    r.Get("/", c.getStuff)
    r.Post("/", c.createStuff)
}

DB Connection Environment Variables (if DB is enabled)

DB_HOST
DB_PORT
DB_NAME
DB_USERNAME
DB_PASSWORD

Documentation

Index

• Variables
• func InitLogger(exitOnFatal bool)
• func ReadJSON(r io.Reader, v interface{}) interface{}
• func SendJSON(w http.ResponseWriter, v interface{})
• func SendStatus(w http.ResponseWriter, s int)
• type APIRouter
  • func (r *APIRouter) Delete(path string, handle func(HTTPContext), v interface{}, ...)
  • func (r *APIRouter) Get(path string, handle func(HTTPContext), interceptors ...HTTPInterceptor)
  • func (r *APIRouter) Post(path string, handle func(HTTPContext), v interface{}, ...)
  • func (r *APIRouter) Put(path string, handle func(HTTPContext), v interface{}, ...)
• type HTTPContext
  • func (ctx *HTTPContext) GetAttribute(key string) interface{}
  • func (ctx *HTTPContext) GetParam(p string) string
  • func (ctx *HTTPContext) SendJSON(v interface{})
  • func (ctx *HTTPContext) SendStatus(s int)
  • func (ctx *HTTPContext) SetAttribute(key string, attr interface{})
• type HTTPInterceptor
• type IHttpController
• type Router
  • func (r *Router) NewAPIRouter(path string) *APIRouter
• type Server
  • func NewServer(controllers ...IHttpController) *Server
  • func (s *Server) Start()

Variables

var Logger *logmatic.Logger

Logger provides application-wide logging

Functions

func InitLogger

func InitLogger(exitOnFatal bool)

InitLogger initializes the application-wide logger

func ReadJSON

func ReadJSON(r io.Reader, v interface{}) interface{}

ReadJSON decodes the provided stream into the given interface.

func SendJSON

func SendJSON(w http.ResponseWriter, v interface{})

SendJSON converts the given interface into JSON and writes to the provided stream.

func SendStatus

func SendStatus(w http.ResponseWriter, s int)

SendStatus writes the given HTTP status code into the provided response stream.

Types

type APIRouter

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

APIRouter represents a router for a specific API

func (*APIRouter) Delete

func (r *APIRouter) Delete(path string, handle func(HTTPContext), v interface{}, interceptors ...HTTPInterceptor)

Delete handles DELETE HTTP requests for the given path

func (*APIRouter) Get

func (r *APIRouter) Get(path string, handle func(HTTPContext), interceptors ...HTTPInterceptor)

Get handles GET HTTP requests for the given path

func (*APIRouter) Post

func (r *APIRouter) Post(path string, handle func(HTTPContext), v interface{}, interceptors ...HTTPInterceptor)

Post handles POST HTTP requests for the given path

func (*APIRouter) Put

func (r *APIRouter) Put(path string, handle func(HTTPContext), v interface{}, interceptors ...HTTPInterceptor)

Put handles PUT HTTP requests for the given path

type HTTPContext

type HTTPContext struct {
	Response http.ResponseWriter
	Request  *http.Request
	Body     interface{}
	// contains filtered or unexported fields
}

HTTPContext provides utility functions for HTTP requests/responses

func (*HTTPContext) GetAttribute

func (ctx *HTTPContext) GetAttribute(key string) interface{}

GetAttribute returns the context-scoped value for the given key

func (*HTTPContext) GetParam

func (ctx *HTTPContext) GetParam(p string) string

GetParam obtains the given parameter key from the request parameters.

func (*HTTPContext) SendJSON

func (ctx *HTTPContext) SendJSON(v interface{})

SendJSON converts the given interface into JSON and writes to the response.

func (*HTTPContext) SendStatus

func (ctx *HTTPContext) SendStatus(s int)

SendStatus writes the given HTTP status code into the response.

func (*HTTPContext) SetAttribute

func (ctx *HTTPContext) SetAttribute(key string, attr interface{})

SetAttribute sets the context-scoped value for the given key

type HTTPInterceptor

type HTTPInterceptor func(ctx HTTPContext) bool

HTTPInterceptor allows for pre-processing request handlers ex. an authentication interceptor could verify a user session

type IHttpController

type IHttpController interface {
	Load(router *Router)
}

IHttpController represents an API that can be loaded into a router

type Router

type Router struct {
	MuxRouter *mux.Router
	DB        *gorm.DB
}

Router maintains routing paths for a single API

func (*Router) NewAPIRouter

func (r *Router) NewAPIRouter(path string) *APIRouter

NewAPIRouter initializes a new API router on at the given path

type Server

type Server struct {
	Port     int
	BasePath string

	EnableDB    bool
	ExitOnFatal bool
	// contains filtered or unexported fields
}

Server represents a REST API server container Default port is 8080 Default path is /api

func NewServer

func NewServer(controllers ...IHttpController) *Server

NewServer creates a route-based REST API server instance

func (*Server) Start

func (s *Server) Start()

Start initializes the API and starts running on the specified port Blocks on current thread