jsend

README

jsend

Golang JSend library

Installation

$ go get github.com/gamegos/jsend

Usage

import "github.com/gamegos/jsend"

See API documentation

Format

Jsend is a very simple json format to wrap your json responses.

{
  "status": "success|fail|error",
  "data": {
    "your data": "here..."
  },
  "message": "error message when status is error"
}

See JSend specification for details.

License

MIT. See LICENSE.

Documentation

Overview

Package jsend implements JSend* specification.

You can wrap your http.ResponseWriter:

jsend.Wrap(w)

Returning object also implements http.ResponseWriter. So you can pass it to your http middlewares.

Success example:

jsend.Wrap(w).
	Data(yourData).
	Send()

// body:
{
	"status": "success",
	"data": {
		"foo": "bar"
	}
}

Status field in response body is derived from http status code. Status is "fail" if code is 4XX, "error" if code is 5XX and "success" otherwise.

Fail:

jsend.Wrap(w).
	Status(400).
	Data(yourData).
	Send()

// body:
{
	"status": "fail",
	"data": {
		"foo": "invalid"
	}
}

Error:

jsend.Wrap(w).
	Status(500).
	Message("we are closed").
	Send()

// body:
{
	"status": "error",
	"message": "we are closed"
}

* See http://labs.omniti.com/labs/jsend for jsend spec.

Example

package main

import (
	"net/http"

	"github.com/gamegos/jsend"
)

func handler(w http.ResponseWriter, r *http.Request) {
	data := map[string]interface{}{
		"id":   1,
		"name": "foo",
	}

	jsend.Wrap(w).
		Data(data).
		Status(201).
		Send()
}

func main() {
	http.ListenAndServe(":8080", http.HandlerFunc(handler))

	/*
		HTTP/1.1 201 Created
		Content-Type: application/json

		{
		  "status": "success",
		  "data": {
		    "id": 1,
		    "name": "foo"
		  }
		}
	*/
}

Index

• Constants
• type JResponseWriter
  • func Wrap(w http.ResponseWriter) JResponseWriter
• type Response
  • func (r *Response) Data(data interface{}) JResponseWriter
  • func (r *Response) Field(key string, value interface{}) JResponseWriter
  • func (r *Response) Header() http.Header
  • func (r *Response) Message(msg string) JResponseWriter
  • func (r *Response) Send() (int, error)
  • func (r *Response) Status(code int) JResponseWriter
  • func (r *Response) Write(data []byte) (int, error)
  • func (r *Response) WriteHeader(code int)

Examples

• Package

Constants

const (
	StatusSuccess = "success"
	StatusError   = "error"
	StatusFail    = "fail"
)

JSend status codes

Types

type JResponseWriter

type JResponseWriter interface {
	http.ResponseWriter

	Data(interface{}) JResponseWriter

	Message(string) JResponseWriter

	Status(int) JResponseWriter

	Field(string, interface{}) JResponseWriter

	Send() (int, error)
}

A JResponseWriter interface extends http.ResponseWriter of go standard library to add utility methods for JSend format.

func Wrap

func Wrap(w http.ResponseWriter) JResponseWriter

Wrap wraps given http.ResponseWriter and returns a response object which implements JResponseWriter interface.

If given parameter already implements JResponseWriter "Wrap" returns it instead of wrapping it again.

type Response

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

Response wraps a http.ResponseWriter type and adds jsend methods. Returning type implements JResponseWriter which extends http.ResponseWriter.

Response buffers given data and writes nothing until "Send" is called.

func (*Response) Data

func (r *Response) Data(data interface{}) JResponseWriter

Data sets response's "data" field with given value.

func (*Response) Field

func (r *Response) Field(key string, value interface{}) JResponseWriter

Field method allows you to set custom response fields.

func (*Response) Header

func (r *Response) Header() http.Header

Header calls Header method of wrapped http.ResponseWriter.

func (*Response) Message

func (r *Response) Message(msg string) JResponseWriter

Message sets response's "message" field with given value.

func (*Response) Send

func (r *Response) Send() (int, error)

Send encodes and writes buffered data to underlying http response object.

func (*Response) Status

func (r *Response) Status(code int) JResponseWriter

Status sets http statusCode. It is a shorthand for "WriteHeader" method in order to keep method chaining.

func (*Response) Write

func (r *Response) Write(data []byte) (int, error)

Write calls Write method of wrapped http.ResponseWriter.

func (*Response) WriteHeader

func (r *Response) WriteHeader(code int)

WriteHeader calls WriteHeader method of wrapped http.ResponseWriter.