googlejson

README

googlejson

A Package to easily create API responses according to Google JSON Style Guide defined here.

Documentation

[] (http://godoc.org/github.com/jasonrichardsmith/googlejson)

Documentation

Overview

Response is a structure designed to hold the contents of a json response to be sent or received with the http package.

You can easily utilize this to marshal results from an http.Reponse

resp, err := http.Get("http://example.com/")
if err != nil {
	log.Fatal(err)
}
gresp, err := googlejson.NewFromHTTPResponse(res)

You can also easily write to a http.ResponseWriter

func MyHandle(w http.ResponseWriter, r *http.Request) {
	gresp := googlejson.New()
	gresp.APIVersion = "1.2"
	code, err:= gresp.WriteToHTTPResponse(w)
}

Or just to a byte slice

gresp := googlejson.New()
gresp.APIVersion = "1.2"
b := gresp.Write()

All the data for the API is stored in Response.Data.Items. These will always be stored as []json.RawMessage which can be retrieved or set with the AddItem, CurrentItem and NextItem methods.

Package googlejson implements json structure defined by the Google JSON Style Guide

See the style guide for more details https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml

Index

• type Data
  • func NewData() *Data
  • func (d *Data) AddField(keys ...string)
  • func (d *Data) AddItem(item interface{}) error
  • func (d *Data) CurrentItem(i interface{}) error
  • func (d *Data) GetFields() []string
  • func (d *Data) ItemsCount() int
  • func (d *Data) NextItem(i interface{}) error
  • func (d *Data) ResetItems()
  • func (d *Data) SetItemCount()
• type Error
  • func NewError() *Error
• type ErrorItem
• type Response
  • func New() *Response
  • func NewFromHTTPResponse(r http.Response) (*Response, error)
  • func (r *Response) Copy() *Response
  • func (r *Response) JSONBytes() ([]byte, error)
  • func (r *Response) WriteToHTTPResponse(w http.ResponseWriter) (int, error)

Types

type Data

type Data struct {
	// Kind is a name of the entity being returned, such as
	// cars, orders, customers etc.
	Kind string `json:"kind,omitempty"`

	// A list of field being returned.  This is a comma separated
	// string so helper methods are provided below.
	Fields string `json:"fields,omitempty"`

	// Etags are an ID for the version of the data you are viewing
	// this allows to identify expired data.
	// More can be read here:
	// https://developers.google.com/gdata/docs/2.0/reference?csw=1#ResourceVersioning
	Etag string `json:"etag,omitempty"`

	// The ID for this request
	ID string `json:"id,omitempty"`

	// Language.
	Lang string `json:"lang,omitempty"`

	// Last time record was updated
	Updated string `json:"updated,omitempty"`

	// Deleted, if this was a delete request did it occur.
	Deleted bool `json:"deleted"`

	// How many items have returned this request.
	CurrentItemCount int `json:"currentItemCount,omitempty"`

	// How many items could be returned in each request.
	ItemsPerPage int `json:"itemsPerPage,omitempty"`

	// Where the list begins in the full list of return values.
	StartIndex int `json:"startIndex,omitempty"`

	// Total number of Items matching request.
	TotalItems int `json:"totalItems,omitempty"`

	// Current page.
	PageIndex int `json:"pageIndex,omitempty"`

	// Total number of pages.
	TotalPages int `json:"totalPages,omitempty"`

	// Direct link to current data set.
	SelfLink string `json:"selfLink,omitempty"`

	// Link to edit results.
	EditLink string `json:"editLink,omitempty"`

	// Link to next result or result set for paginated results.
	NextLink string `json:"nextLink,omitempty"`

	// Link to previous result or result set for paginated results.
	PreviousLink string `json:"previousLink,omitempty"`

	// An array of items -  this is the actual data.
	Items []json.RawMessage `json:"items,omitempty"`
	// contains filtered or unexported fields
}

Data structure holds all information specific to the data in the Response and the data itself

func NewData

func NewData() *Data

Shortcut to new data object.

func (*Data) AddField

func (d *Data) AddField(keys ...string)

Add a single field to the list of fields to be returned.

func (*Data) AddItem

func (d *Data) AddItem(item interface{}) error

Add a single data item to the list of Items to be returned.

func (*Data) CurrentItem

func (d *Data) CurrentItem(i interface{}) error

Retrieve the item at current pointer position.

func (*Data) GetFields

func (d *Data) GetFields() []string

Get a list of fields.

func (*Data) ItemsCount

func (d *Data) ItemsCount() int

Get count of current items in the Items list.

func (*Data) NextItem

func (d *Data) NextItem(i interface{}) error

Retrieve the next item.

func (*Data) ResetItems

func (d *Data) ResetItems()

Reset Item pointer to 0.

func (*Data) SetItemCount

func (d *Data) SetItemCount()

Set the item count to the number of Items to be returned.

type Error

type Error struct {
	// Integer code representing an error code
	Code int `json:"code,omitempty"`

	// Message for error.
	Message string `json:"message,omitempty"`

	// An array of error message item data.
	Errors []ErrorItem `json:"errors,omitempty"`
}

Error object to be returned.

func NewError

func NewError() *Error

Shortcut to create Error.

type ErrorItem

type ErrorItem struct {
	Message        string `json:"message,omitempty"`
	Location       string `json:"location,omitempty"`
	LocationType   string `json:"locationType,omitempty"`
	ExtendedHelper string `json:"extendedHelper,omitempty"`
	Domains        string `json:"domain,omitempty"`
	Reason         string `json:"reason,omitempty"`
	SendReport     string `json:"sendReport,omitempty"`
}

Details relating to the error being returned. For more details see https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml

type Response

type Response struct {
	// Version of API being served or received.
	APIVersion string `json:"apiVersion,omitempty"`

	// Context is a parameter submitted by requestor
	// as in an http.Request, this will be returned
	// to the client for context.
	Context string `json:"context,omitempty"`

	// ID is a unique ID assigned to the request
	// if the API will need to reference a transaction.
	ID string `json:"id,omitempty"`

	// Method represents the operation performed.
	Method string `json:"method,omitempty"`

	// Params are a list of parameters submitted to the API.
	Params map[string]string `json:"params,omitempty"`

	// Data holds the actual data that was returned.
	Data `json:"data,omitempty"`

	// Errors to be returned.
	Error `json:"error,omitempty"`
}

Type is the top level json object. It should contain at least one data object or one error.

func New

func New() *Response

Shortcut to create a new Response

func NewFromHTTPResponse

func NewFromHTTPResponse(r http.Response) (*Response, error)

Shortcut to create a response from an http.Response

func (*Response) Copy

func (r *Response) Copy() *Response

Shortcut to create a copy of the response. This means you can set common settings, and re-use the base Response.

func (*Response) JSONBytes

func (r *Response) JSONBytes() ([]byte, error)

Write the struct to byte[]. SetItemCount will be called prior to writing.

func (*Response) WriteToHTTPResponse

func (r *Response) WriteToHTTPResponse(w http.ResponseWriter) (int, error)

Shortcut to write to an http.ResponseWriter.