https://github.com/ory/herodot
A lightweight Go library for writing responses and errors to HTTP
https://github.com/ory/herodot
Last synced: about 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 (about 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).