README
¶
Murphy
An opinionated view on JSON APIs, and a short implementation in Golang.
tl;dr
type Request struct { Name string }
type Response struct { Greeting string }
func Hello(ctx *murphy.HttpContext, req *Request, resp *Response) error {
if len(req.Name) == 0 {
return murphy.BadRequestErrorf("name missing")
}
resp.Greeting = "Hello " + req.Name
return nil
}
and installed as such
http.Handle("/hello", murphy.JsonHandler(Hello))
log.Fatal(http.ListenAndServe(":8080", nil))
Remote APIs
At the simplest level, remote APIs such as "JSON APIs" can be looked at through the lens of normal API design. The domain the API deals with has its concepts, lexicon, short and long lived entities, and operations to create, mutate, discover / list, or otherwise destroy these.
Where things depart from simple API design is the remotness. This introduces two complexities: transport, and error handling.
From the client's perspective (i.e. the caller), invoking a remote method results in one of two states: unknown where you do not know whether things succeeded or failed; and known where you either know things succeeded, or know they failed. The former typically occurs with timeout, network separation, or any other I/O level problem; the latter is a property of the API being invoked. Dealing with unknown state is fun, and such a large topic by itself that we're goind to elude it here. Dealing with known state is almost similar as API design... you got it, error handling.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func JsonHandler ¶
func JsonHandler(fn interface{}) func(w http.ResponseWriter, r *http.Request)
JsonHandler converts a function capable of being a handler for JSON APIs into a net/http compatible handler. To serve JSON API requests, a function may take either a struct as arguments (to be converted from JSON passed in the body), an http.Request, both or none, and must return a struct pointer, and an error.
Types ¶
type BadRequestError ¶
type BadRequestError struct {
// contains filtered or unexported fields
}
BadRequestError is the specific error which handlers can return to Murphy to signal that the request was erroneous, and therefore a 400 status should be returned (as opposed to a 500).
func BadRequestErrorf ¶
func BadRequestErrorf(format string, args ...interface{}) *BadRequestError
BadRequestErrorf constructs a BadRequestError in a similar fashion than one would use `fmt.Errorf`.
func (BadRequestError) MarshalJSON ¶
func (e BadRequestError) MarshalJSON() ([]byte, error)
MarshalJSON marshalls a BadRequestError as a JSON object with a single entry `err` which contains the string representation of the error it wraps.
type HttpContext ¶
func NewHttpContext ¶
func NewHttpContext(w http.ResponseWriter, r *http.Request) HttpContext
Source Files