package module
v0.2.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: May 6, 2019 License: MIT Imports: 7 Imported by: 2



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.

GoDoc CI Status Go Report Card

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.


go get -u

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

import ""

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

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",
import ""

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"))

Will render something like:

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




This section is empty.


This section is empty.


func R

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.


type ErrResponse

type ErrResponse struct {

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 {

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


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL