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 https://granitic.io/ref/json-web-services

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: https://granitic.io/ref/json-web-services

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: https://granitic.io/ref/json-web-services

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 MarshalingWriter
  • func (mw *MarshalingWriter) MarshalAndWrite(data interface{}, w http.ResponseWriter) error
• type Unmarshaller
  • func (ju *Unmarshaller) Unmarshall(ctx context.Context, req *http.Request, wsReq *ws.Request) 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 {
}

BodyOrErrorWrapper is an 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{}

GraniticJSONErrorFormatter 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
}

GraniticJSONResponseWrapper is a 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 MarshalingWriter

type MarshalingWriter 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
}

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

func (*MarshalingWriter) MarshalAndWrite

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

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

type Unmarshaller

type Unmarshaller struct {
	FrameworkLogger logging.Logger
}

Unmarshaller is a component wrapper over Go's JSON decoder.

func (*Unmarshaller) Unmarshall

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

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