README
¶
go-respond
A Go package for handling common HTTP JSON responses.
Installation
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:
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", "billy@example.com"},
{2, "Joan", "joan@example.com"},
}
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 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.
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. Here's an example:
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.
Documentation
¶
Index ¶
- type DefaultMessageResponse
- type Response
- func (resp *Response) Accepted(v interface{})
- func (resp *Response) AddHeader(key string, value string) *Response
- func (resp *Response) BadGateway(v interface{})
- func (resp *Response) BadRequest(v interface{})
- func (resp *Response) Conflict(v interface{})
- func (resp *Response) Created(v interface{})
- func (resp *Response) DefaultMessage() *Response
- func (resp *Response) DeleteHeader(key string) *Response
- func (resp *Response) Forbidden(v interface{})
- func (resp *Response) GatewayTimeout(v interface{})
- func (resp *Response) Gone(v interface{})
- func (resp *Response) InternalServerError(v interface{})
- func (resp *Response) LengthRequired(v interface{})
- func (resp *Response) MethodNotAllowed(v interface{})
- func (resp *Response) NoContent()
- func (resp *Response) NotAcceptable(v interface{})
- func (resp *Response) NotFound(v interface{})
- func (resp *Response) NotImplemented(v interface{})
- func (resp *Response) Ok(v interface{})
- func (resp *Response) PreconditionFailed(v interface{})
- func (resp *Response) RequestEntityTooLarge(v interface{})
- func (resp *Response) ServiceUnavailable(v interface{})
- func (resp *Response) Unauthorized(v interface{})
- func (resp *Response) UnprocessableEntity(v interface{})
- func (resp *Response) UnsupportedMediaType(v interface{})
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DefaultMessageResponse ¶
DefaultMessageResponse is for transporting a default http message
type Response ¶
type Response struct {
Writer http.ResponseWriter
Headers map[string]string
DefMessage bool
}
Response is the HTTP response
func NewResponse ¶
func NewResponse(w http.ResponseWriter) *Response
NewResponse creates and returns a new response
func (*Response) Accepted ¶
func (resp *Response) Accepted(v interface{})
Accepted returns a 202 Accepted JSON response
func (*Response) BadGateway ¶
func (resp *Response) BadGateway(v interface{})
BadGateway returns a 502 Bad Gateway JSON response
func (*Response) BadRequest ¶
func (resp *Response) BadRequest(v interface{})
BadRequest returns a 400 Bad Request JSON response
func (*Response) Conflict ¶
func (resp *Response) Conflict(v interface{})
Conflict returns a 409 Conflict JSON response
func (*Response) Created ¶
func (resp *Response) Created(v interface{})
Created returns a 201 Created JSON response
func (*Response) DefaultMessage ¶
func (*Response) DeleteHeader ¶
DeleteHeader deletes a single header from the response
func (*Response) Forbidden ¶
func (resp *Response) Forbidden(v interface{})
Forbidden returns a 403 Forbidden JSON response
func (*Response) GatewayTimeout ¶
func (resp *Response) GatewayTimeout(v interface{})
GatewayTimeout returns a 504 Gateway Timeout JSON response
func (*Response) Gone ¶ added in v1.6.0
func (resp *Response) Gone(v interface{})
Gone returns a 410 Gone JSON response
func (*Response) InternalServerError ¶
func (resp *Response) InternalServerError(v interface{})
InternalServerError returns a 500 Internal Server Error JSON response
func (*Response) LengthRequired ¶
func (resp *Response) LengthRequired(v interface{})
LengthRequired returns a 411 Length Required JSON response
func (*Response) MethodNotAllowed ¶
func (resp *Response) MethodNotAllowed(v interface{})
MethodNotAllowed returns a 405 Method Not Allowed JSON response
func (*Response) NoContent ¶
func (resp *Response) NoContent()
NoContent returns a 204 No Content JSON response
func (*Response) NotAcceptable ¶
func (resp *Response) NotAcceptable(v interface{})
NotAcceptable returns a 406 Not Acceptable JSON response
func (*Response) NotFound ¶
func (resp *Response) NotFound(v interface{})
NotFound returns a 404 Not Found JSON response
func (*Response) NotImplemented ¶
func (resp *Response) NotImplemented(v interface{})
NotImplemented returns a 501 Not Implemented JSON response
func (*Response) PreconditionFailed ¶
func (resp *Response) PreconditionFailed(v interface{})
PreconditionFailed returns a 412 Precondition Failed JSON response
func (*Response) RequestEntityTooLarge ¶
func (resp *Response) RequestEntityTooLarge(v interface{})
RequestEntityTooLarge returns a 413 Request Entity Too Large JSON response
func (*Response) ServiceUnavailable ¶
func (resp *Response) ServiceUnavailable(v interface{})
ServiceUnavailable returns a 503 Service Unavailable JSON response
func (*Response) Unauthorized ¶
func (resp *Response) Unauthorized(v interface{})
Unauthorized returns a 401 Unauthorized JSON response
func (*Response) UnprocessableEntity ¶
func (resp *Response) UnprocessableEntity(v interface{})
UnprocessableEntity returns a 422 Unprocessable Entity JSON response
func (*Response) UnsupportedMediaType ¶
func (resp *Response) UnsupportedMediaType(v interface{})
UnsupportedMediaType returns a 415 Unsupported Media Type JSON response
Source Files