res

README

res

Package res provides handy primitives for working with JSON in Go HTTP servers and clients via go-chi/render. It is designed to be lightweight and easy to extend.

I originally wrote something similar to this in two UBC Launch Pad projects that I worked on - Inertia and Pinpoint - and felt like it might be useful to have it as a standalone package.

It is currently a work-in-progress - I'm hoping to continue refining the API and add more robust tests.

Usage

go get -u github.com/bobheadxi/res

Clientside

I implemented something similar to res in Inertia. It has a client that shows how you might leverage this library: inertia/client.Client

import "github.com/bobheadxi/res"

func main() {
  resp, err := http.Get(os.Getenv("URL"))
  if err != nil {
    log.Fatal(err)
  }
  var info string
  b, err := res.Unmarshal(resp.Body, res.KV{Key: "info", Value: &info})
  if err != nil {
    log.Fatal(err)
  }
  if err := b.Error(); err != nil {
    log.Fatal(err)
  }
  println(info)
}

Serverside

OK

import "github.com/bobheadxi/res"

func Handler(w http.ResponseWriter, r *http.Request) {
  res.R(w, r, res.MsgOK("hello world!",
    "stuff", "amazing",
    "details", res.M{"world": "hello"}))
}

Will render something like:

{
  "code": 200,
  "message": "hello world",
  "request_id": "12345",
  "body": {
    "stuff": "amazing",
    "details": {
      "world": "hello",
    }
  }
}

Error

import "github.com/bobheadxi/res"

func Handler(w http.ResponseWriter, r *http.Request) {
  body, err := ioutil.ReadAll(r.Body)
  if err != nil {
    res.R(w, r, res.ErrBadRequest("failed to read request",
      "error", err,
      "details", "something"))
    return
  }
}

Will render something like:

{
  "code": 400,
  "message": "failed to read request",
  "request_id": "12345",
  "error": "could not read body",
  "body": {
    "details": "something",
  }
}

Documentation

Index

• func R(w http.ResponseWriter, r *http.Request, v render.Renderer)
• func Unmarshal(r io.Reader, kvs ...KV) (*base.Response, error)
• type ErrResponse
  • func Err(message string, code int, kvs ...interface{}) *ErrResponse
  • func ErrBadRequest(message string, kvs ...interface{}) *ErrResponse
  • func ErrForbidden(message string, kvs ...interface{}) *ErrResponse
  • func ErrInternalServer(message string, err error, kvs ...interface{}) *ErrResponse
  • func ErrNotFound(message string, kvs ...interface{}) *ErrResponse
  • func ErrUnauthorized(message string, kvs ...interface{}) *ErrResponse
• type KV
• type M
• type MsgResponse
  • func Msg(message string, code int, kvs ...interface{}) *MsgResponse
  • func MsgOK(message string, kvs ...interface{}) *MsgResponse

Functions

func R

func R(w http.ResponseWriter, r *http.Request, v render.Renderer)

R is an alias for go-chi/render.Render

func Unmarshal

func Unmarshal(r io.Reader, kvs ...KV) (*base.Response, error)

Unmarshal reads the response and unmarshalls the BaseResponse as well any requested key-value pairs. For example:

var prop = map[string]string
api.Unmarshal(resp.Body, api.KV{Key: "prop", Value: &prop})

Values provided in KV.Value MUST be explicit pointers, even if the value is a pointer type, ie maps and slices.

Types

type ErrResponse

type ErrResponse struct {
	*base.Response
}

ErrResponse is the template for a typical HTTP response for errors

func Err

func Err(message string, code int, kvs ...interface{}) *ErrResponse

Err is a basic error response constructor

func ErrBadRequest

func ErrBadRequest(message string, kvs ...interface{}) *ErrResponse

ErrBadRequest is a shortcut for bad requests

func ErrForbidden

func ErrForbidden(message string, kvs ...interface{}) *ErrResponse

ErrForbidden is a shortcut for forbidden requests

func ErrInternalServer

func ErrInternalServer(message string, err error, kvs ...interface{}) *ErrResponse

ErrInternalServer is a shortcut for internal server errors. It should be accompanied by an actual error.

func ErrNotFound

func ErrNotFound(message string, kvs ...interface{}) *ErrResponse

ErrNotFound is a shortcut for forbidden requests

func ErrUnauthorized

func ErrUnauthorized(message string, kvs ...interface{}) *ErrResponse

ErrUnauthorized is a shortcut for unauthorized requests

type KV

type KV struct {
	Key   string
	Value interface{}
}

KV is used for defining specific values to be unmarshalled from BaseResponse data

type M

type M map[string]interface{}

M is an alias for a map

type MsgResponse

type MsgResponse struct {
	*base.Response
}

MsgResponse is the template for a typical HTTP response for messages

func Msg

func Msg(message string, code int, kvs ...interface{}) *MsgResponse

Msg is a shortcut for non-error statuses

func MsgOK

func MsgOK(message string, kvs ...interface{}) *MsgResponse

MsgOK is a shortcut for an ok-status response