https://github.com/ory/herodot
A lightweight Go library for writing responses and errors to HTTP
https://github.com/ory/herodot
Last synced: 2 months ago
JSON representation
A lightweight Go library for writing responses and errors to HTTP
- Host: GitHub
- URL: https://github.com/ory/herodot
- Owner: ory
- License: apache-2.0
- Created: 2016-11-24T09:08:43.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2025-03-18T10:46:52.000Z (3 months ago)
- Last Synced: 2025-04-12T00:28:59.582Z (2 months ago)
- Language: Go
- Homepage:
- Size: 450 KB
- Stars: 118
- Watchers: 11
- Forks: 17
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# herodot
[](https://slack.ory.sh/)
[](https://travis-ci.org/ory/herodot)
[](https://coveralls.io/github/ory/herodot?branch=master)---
Herodot is a lightweight SDK for writing RESTful responses. It is comparable to
[render](https://github.com/unrolled/render) but provides easier error handling.
The error model implements the well established
[Google API Design Guide](https://cloud.google.com/apis/design/errors). Herodot
currently supports only JSON responses but can be extended easily.Herodot is used by [ORY Hydra](https://github.com/ory/hydra) and serves millions
of requests already.## Installation
Herodot is versioned using
[go modules](https://blog.golang.org/using-go-modules) and works best with
[pkg/errors](https://github.com/pkg/errors). To install it, run```
go get -u github.com/ory/herodot
```## Upgrading
Tips on upgrading can be found in [UPGRADE.md](UPGRADE.md)
## Usage
Using Herodot is straightforward. The examples below will help you get started.
### JSON
Herodot supplies an interface, allowing to return errors in many data formats
like XML and others. Currently, it supports only JSON.#### Write responses
```go
var hd = herodot.NewJSONWriter(nil)func GetHandler(rw http.ResponseWriter, r *http.Request) {
// run your business logic here
hd.Write(rw, r, map[string]interface{}{
"key": "value"
})
}type MyStruct struct {
Key string `json:"key"`
}func GetHandlerWithStruct(rw http.ResponseWriter, r *http.Request) {
// business logic
hd.Write(rw, r, &MyStruct{Key: "value"})
}func PostHandlerWithStruct(rw http.ResponseWriter, r *http.Request) {
// business logic
hd.WriteCreated(rw, r, "/path/to/the/resource/that/was/created", &MyStruct{Key: "value"})
}func SomeHandlerWithArbitraryStatusCode(rw http.ResponseWriter, r *http.Request) {
// business logic
hd.WriteCode(rw, r, http.StatusAccepted, &MyStruct{Key: "value"})
}func SomeHandlerWithArbitraryStatusCode(rw http.ResponseWriter, r *http.Request) {
// business logic
hd.WriteCode(rw, r, http.StatusAccepted, &MyStruct{Key: "value"})
}
```#### Dealing with errors
```go
var writer = herodot.NewJSONWriter(nil)func GetHandlerWithError(rw http.ResponseWriter, r *http.Request) {
if err := someFunctionThatReturnsAnError(); err != nil {
hd.WriteError(w, r, err)
return
}// ...
}func GetHandlerWithErrorCode(rw http.ResponseWriter, r *http.Request) {
if err := someFunctionThatReturnsAnError(); err != nil {
hd.WriteErrorCode(w, r, http.StatusBadRequest, err)
return
}// ...
}
```### Errors
Herodot implements the error model of the well established
[Google API Design Guide](https://cloud.google.com/apis/design/errors).
Additionally, it makes the fields `request` and `reason` available. A complete
Herodot error response looks like this:```json
{
"error": {
"code": 404,
"status": "some-status",
"request": "foo",
"reason": "some-reason",
"details": [{ "foo": "bar" }],
"message": "foo"
}
}
```To add context to your errors, implement `herodot.ErrorContextCarrier`. If you
only want to set the status code of errors implement
[herodot.StatusCodeCarrier](https://github.com/ory/herodot/blob/master/error.go#L22-L26).