herodot

README

herodot

---

Herodot is a lightweight SDK for writing RESTful responses. You can compare it to render, although it currently supports only JSON.

Herodot is used by Hydra and servers millions of requests already.

Installation

Herodot is versioned using glide and works best with pkg/errors. To install it, run

go get -u github.com/ory/herodot

Examples

Using Herodot is straight forward, these examples will help you getting started.

JSON

Herodot supplies an interface, so it's possible to write many outputs, such as XML and others. For now, JSON is supported.

Write responses

var writer = herodot.NewJSONWriter(nil)

func GetHandler(rw http.ResponseWriter, r *http.Request) {
	writer.Write(rw, r, map[string]interface{}{
	    "key": "value"
	})
}

type MyStruct struct {
    Key string `json:"key"`
}

func GetHandlerWithStruct(rw http.ResponseWriter, r *http.Request) {
	writer.Write(rw, r, &MyStruct{Key: "value"})
}

func PostHandlerWithStruct(rw http.ResponseWriter, r *http.Request) {
	writer.WriteCreated(rw, r, "/path/to/the/resource/that/was/created", &MyStruct{Key: "value"})
}

func SomeHandlerWithArbitraryStatusCode(rw http.ResponseWriter, r *http.Request) {
	writer.WriteCode(rw, r, http.StatusAccepted, &MyStruct{Key: "value"})
}

func SomeHandlerWithArbitraryStatusCode(rw http.ResponseWriter, r *http.Request) {
	writer.WriteCode(rw, r, http.StatusAccepted, &MyStruct{Key: "value"})
}

Dealing with errors

var writer = herodot.NewJSONWriter(nil)

func GetHandlerWithError(rw http.ResponseWriter, r *http.Request) {
    if err := someFunctionThatReturnsAnError(); err != nil {
        writer.WriteError(w, r, err)
        return
    }
    
    // ...
}

func GetHandlerWithErrorCode(rw http.ResponseWriter, r *http.Request) {
    if err := someFunctionThatReturnsAnError(); err != nil {
        writer.WriteErrorCode(w, r, http.StatusBadRequest, err)
        return
    }
    
    // ...
}

Documentation

Index

• type JSONWriter
  • func NewJSONWriter(logger logrus.FieldLogger) *JSONWriter
  • func (h *JSONWriter) Write(w http.ResponseWriter, r *http.Request, e interface{})
  • func (h *JSONWriter) WriteCode(w http.ResponseWriter, r *http.Request, code int, e interface{})
  • func (h *JSONWriter) WriteCreated(w http.ResponseWriter, r *http.Request, location string, e interface{})
  • func (h *JSONWriter) WriteError(w http.ResponseWriter, r *http.Request, err error)
  • func (h *JSONWriter) WriteErrorCode(w http.ResponseWriter, r *http.Request, code int, err error)
• type StatusCodeCarrier
• type Writer

Types

type JSONWriter

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

JSONWriter outputs JSON.

func NewJSONWriter

func NewJSONWriter(logger logrus.FieldLogger) *JSONWriter

NewJSONWriter returns a JSONWriter

func (*JSONWriter) Write

func (h *JSONWriter) Write(w http.ResponseWriter, r *http.Request, e interface{})

Write a response object to the ResponseWriter with status code 200.

func (*JSONWriter) WriteCode

func (h *JSONWriter) WriteCode(w http.ResponseWriter, r *http.Request, code int, e interface{})

WriteCode writes a response object to the ResponseWriter and sets a response code.

func (*JSONWriter) WriteCreated

func (h *JSONWriter) WriteCreated(w http.ResponseWriter, r *http.Request, location string, e interface{})

WriteCreated writes a response object to the ResponseWriter with status code 201 and the Location header set to location.

func (*JSONWriter) WriteError

func (h *JSONWriter) WriteError(w http.ResponseWriter, r *http.Request, err error)

WriteError writes an error to ResponseWriter and tries to extract the error's status code by asserting StatusCodeCarrier. If the error does not implement StatusCodeCarrier, the status code is set to 500.

func (*JSONWriter) WriteErrorCode

func (h *JSONWriter) WriteErrorCode(w http.ResponseWriter, r *http.Request, code int, err error)

WriteErrorCode writes an error to ResponseWriter and forces an error code.

type StatusCodeCarrier

type StatusCodeCarrier interface {
	// StatusCode returns the status code of this error.
	StatusCode() int
}

StatusCodeCarrier can be implemented in an error to support setting status codes in the error itself.

type Writer

type Writer interface {
	// Write a response object to the ResponseWriter with status code 200.
	Write(w http.ResponseWriter, r *http.Request, e interface{})

	// WriteCode writes a response object to the ResponseWriter and sets a response code.
	WriteCode(w http.ResponseWriter, r *http.Request, code int, e interface{})

	// WriteCreated writes a response object to the ResponseWriter with status code 201 and
	// the Location header set to location.
	WriteCreated(w http.ResponseWriter, r *http.Request, location string, e interface{})

	// WriteError writes an error to ResponseWriter and tries to extract the error's status code by
	// asserting StatusCodeCarrier. If the error does not implement StatusCodeCarrier, the status code
	// is set to 500.
	WriteError(w http.ResponseWriter, r *http.Request, err error)

	// WriteErrorCode writes an error to ResponseWriter and forces an error code.
	WriteErrorCode(w http.ResponseWriter, r *http.Request, code int, err error)
}

Writer is a helper to write arbitrary data to a ResponseWriter