Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nicklaw5/go-respond
A Go package for handling common HTTP JSON responses.
https://github.com/nicklaw5/go-respond
api go golang json json-api
Last synced: about 1 month ago
JSON representation
A Go package for handling common HTTP JSON responses.
- Host: GitHub
- URL: https://github.com/nicklaw5/go-respond
- Owner: nicklaw5
- License: mit
- Created: 2017-03-12T21:00:54.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2021-09-24T20:08:26.000Z (about 3 years ago)
- Last Synced: 2024-10-25T05:25:43.321Z (about 2 months ago)
- Topics: api, go, golang, json, json-api
- Language: Go
- Homepage: https://godoc.org/github.com/nicklaw5/go-respond
- Size: 41 KB
- Stars: 55
- Watchers: 2
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - go-respond - Go package for handling common HTTP JSON responses. (JSON / Search and Analytic Databases)
- awesome-go - go-respond - A Go package for handling common HTTP JSON responses. - ★ 13 (Utilities)
- awesome-go-extra - go-respond - 03-12T21:00:54Z|2021-09-24T20:08:26Z| (JSON / Advanced Console UIs)
README
# go-respond
A Go package for handling common HTTP JSON responses.
[](https://godoc.org/github.com/nicklaw5/go-respond)
[](https://travis-ci.org/nicklaw5/go-respond)
[](https://coveralls.io/github/nicklaw5/go-respond)
[](https://goreportcard.com/report/github.com/nicklaw5/go-respond)
## Installation
```bash
go get github.com/nicklaw5/go-respond
```
## Usage
The goal of `go-respond` is to take most of the grunt work out preparing your JSON response. Here's a simple example:
```go
package main
import (
"net/http"
resp "github.com/nicklaw5/go-respond"
)
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
func main() {
http.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {
users := []User{
{1, "Billy", "[email protected]"},
{2, "Joan", "[email protected]"},
}
resp.NewResponse(w).Ok(users)
})
http.ListenAndServe(":8080", nil)
}
```
## Response Methods
| Response Code | Method Name |
| :---------- | :------------ |
| 200 | Ok() |
| 201 | Created() |
| 202 | Accepted() |
| 204 | NoContent() |
| 400 | BadRequest() |
| 401 | Unauthorized() |
| 403 | Forbidden() |
| 404 | NotFound() |
| 405 | MethodNotAllowed() |
| 406 | NotAcceptable() |
| 409 | Conflict() |
| 410 | Gone() |
| 411 | LengthRequired() |
| 412 | PreconditionFailed() |
| 413 | RequestEntityTooLarge() |
| 415 | UnsupportedMediaType() |
| 422 | UnprocessableEntity() |
| 500 | InternalServerError() |
| 501 | NotImplemented() |
| 502 | BadGateway() |
| 503 | ServiceUnavailable() |
| 504 | GatewayTimeout() |
See [here](https://httpstatuses.com/) for a complete list of HTTP responses, along with an explanation of each.
Please submit a PR if you want to add to this list. Only the most common response types have been included.
## To Long, Don't Write
Sometimes you don't need to return a specific content-message but don't want the response body to be empty.
In this case you can use the `DefaultMessage()` for responding with json containing the default message for the corresponding status code.
```go
package main
import (
"net/http"
resp "github.com/nicklaw5/go-respond"
)
func main() {
http.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {
// ...
if !authenticated {
resp.NewResponse(w).DefaultMessage().
Unauthorized(nil)
}
// ...
})
http.ListenAndServe(":8080", nil)
}
```
Would respond with `{"status":401,"message":"Unauthorized"}`
## Handling Errors
The best option for handling errors that may occur while marshalling the JSON response, is to use [Negroni's Recovery middleware](https://github.com/urfave/negroni#recovery). Here's an example:
```go
package main
import (
"net/http"
"github.com/urfave/negroni"
resp "github.com/nicklaw5/go-respond"
)
type Response struct {
Success bool `json:"success"`
}
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
resp.NewResponse(w).Ok(&Response{true})
})
n := negroni.New()
recovery := negroni.NewRecovery()
recovery.ErrorHandlerFunc = func(error interface{}) {
// do something with the unexpected error
}
n.Use(recovery)
n.UseHandler(mux)
http.ListenAndServe(":8080", n)
}
```
## License
This package is distributed under the terms of the [MIT](LICENSE) License.