json

Documentation

Overview

Package json defines types that are specific to handling web service requests and responses as JSON. Components implementing this type will be created when you enable the JsonWs facility. For more information on JSON web services in Granitic, see http://granitic.io/1.0/ref/json.

Marshalling and unmarshalling

The response writer and unmarshaller defined in this package are thin wrappers over the Go's built-in json handling types. See https://golang.org/pkg/encoding/json

Response wrapping

By default, any data serialised to JSON will first be wrapped with a containing data structure by an instance of GraniticJSONResponseWrapper. This means that all responses share a common top level structure for finding the body of the response or errors if they exist. For more information on this behaviour (and how to override it) see: http://granitic.io/1.0/ref/json#wrapping

Error formatting

Any service errors found in a response are formatted by GraniticJSONErrorFormatter before being serialised to JSON. For more information on this behaviour (and how to override it) see: http://granitic.io/1.0/ref/json#errors

Compatibility with existing service APIs

A hurdle to migrating existing Java and .NET services to Go is that those languages allow JSON frameworks to write and read from member variables that start with lowercase characters. Go's rules for json decoding will map a JSON field with a lowercase first letter into a struct field with an uppercase letter (e.g. name wil be parsed into Name).

No such logic exists for forcing Name to be serialised as name other than defining tags on your JSON struct. The CamelCase method defined below can take an entire Go struct and create a copy of the object with all capitalised field names replaced with lowercase equivalents.

The method must be explicitly called in your handler's logic like:

wsResponse.Body = json.CamelCase(body)

This feature should be considered experimental.

Index

• func CamelCase(u interface{}) (interface{}, error)
• type BodyOrErrorWrapper
  • func (rw *BodyOrErrorWrapper) WrapResponse(body interface{}, errors interface{}) interface{}
• type GraniticJSONErrorFormatter
  • func (ef *GraniticJSONErrorFormatter) FormatErrors(errors *ws.ServiceErrors) interface{}
• type GraniticJSONResponseWrapper
  • func (rw *GraniticJSONResponseWrapper) WrapResponse(body interface{}, errors interface{}) interface{}
• type JsonMarshalingWriter
  • func (mw *JsonMarshalingWriter) MarshalAndWrite(data interface{}, w http.ResponseWriter) error
• type StandardJSONUnmarshaller
  • func (ju *StandardJSONUnmarshaller) Unmarshall(ctx context.Context, req *http.Request, wsReq *ws.WsRequest) error

Functions

func CamelCase

func CamelCase(u interface{}) (interface{}, error)

CamelCase converts the supplied data into a map[string]interface{} representation then recursively renames any keys that start with an uppercase letter to the same name with a lowercase first letter.

Types

type BodyOrErrorWrapper

type BodyOrErrorWrapper struct {
}

Implementation of ResponseWrapper that just returns the body object if not nil or the errors object if not nil

func (*BodyOrErrorWrapper) WrapResponse

func (rw *BodyOrErrorWrapper) WrapResponse(body interface{}, errors interface{}) interface{}

WrapResponse returns body if not nil or errors if not nil. Otherwise returns nil

type GraniticJSONErrorFormatter

type GraniticJSONErrorFormatter struct{}

Converts service errors into a data structure for consistent serialisation to JSON.

func (*GraniticJSONErrorFormatter) FormatErrors

func (ef *GraniticJSONErrorFormatter) FormatErrors(errors *ws.ServiceErrors) interface{}

FormatErrors converts all of the errors present in the supplied objects into a structure suitable for serialisation.

type GraniticJSONResponseWrapper

type GraniticJSONResponseWrapper struct {
	ErrorsFieldName string
	BodyFieldName   string
}

Component for wrapping response data before it is serialised. The wrapping structure is a map[string]string

func (*GraniticJSONResponseWrapper) WrapResponse

func (rw *GraniticJSONResponseWrapper) WrapResponse(body interface{}, errors interface{}) interface{}

WrapResponse creates a map[string]string to wrap the supplied response body and errors.

type JsonMarshalingWriter

type JsonMarshalingWriter struct {
	// Format generated JSON in a human readable form.
	PrettyPrint bool

	// The characters (generally tabs or spaces) to indent child elements in pretty-printed JSON.
	IndentString string

	// A prefix for each line of generated JSON.
	PrefixString string
}

Component wrapper over Go's json.Marshalxx functions. Serialises a struct to JSON and writes it to the HTTP response output stream.

func (*JsonMarshalingWriter) MarshalAndWrite

func (mw *JsonMarshalingWriter) MarshalAndWrite(data interface{}, w http.ResponseWriter) error

MarshalAndWrite serialises the supplied interface to JSON and writes it to the HTTP response output stream.

type StandardJSONUnmarshaller

type StandardJSONUnmarshaller struct {
	FrameworkLogger logging.Logger
}

Component wrapper over Go's JSON decoder.

func (*StandardJSONUnmarshaller) Unmarshall

func (ju *StandardJSONUnmarshaller) Unmarshall(ctx context.Context, req *http.Request, wsReq *ws.WsRequest) error

Unmarshall uses Go's JSON decoder to parse a HTTP request body into a struct.