Documentation
¶
Overview ¶
Package rest provides support for REST/JSON content negotiation, writing JSON to the response stream, and REST-specific error messages.
Index ¶
- Variables
- func AcceptsJson(r *http.Request) bool
- func AcceptsUtf8(r *http.Request) bool
- func ContentIsJson(r *http.Request) bool
- func HasValidOrigin(r *http.Request, validOriginSuffix string) bool
- func Middleware(ctx context.Context, w http.ResponseWriter, r *http.Request) context.Context
- func Param(ctx context.Context, name string) string
- func ReadJSON(r *http.Request, dst interface{}) error
- func WriteJSON(w http.ResponseWriter, src interface{}) error
- type Message
- type Response
Constants ¶
This section is empty.
Variables ¶
var ( NoContent = Response{ http.StatusNoContent, nil, } ErrNotFound = Response{ http.StatusNotFound, &Message{"The requested resource could not be located."}, } ErrConflict = Response{ http.StatusConflict, &Message{"The requested operation conflicts with the existing state of that resource."}, } ErrMethodNotAllowed = Response{ http.StatusMethodNotAllowed, &Message{"That HTTP verb is not permitted at this endpoint."}, } )
Functions ¶
func AcceptsJson ¶
AcceptsJson tests whether the request's Accept header is set in such a way that it will accept JSON responses.
func AcceptsUtf8 ¶
AcceptsUtf8 tests whether the request's Accept-Charset header is set in such a way that it will accept UTF-8 responses.
func ContentIsJson ¶
ContentIsJson determines whether r's Content-Type header describes it as JSON in the UTF-8 character encoding.
func HasValidOrigin ¶
HasValidOrigin tests whether the request's Origin header (always set automatically by browsers during XHR) matches the domain suffix in validOriginSuffix. For instance, an Origin of "foo.theinformation.com" would be valid if validOriginSuffix were "theinformation.com", but not if it were bar.theinformation.com. If validOriginSuffix is an empty string, HasValidOrigin always returns true.
func Middleware ¶
Middleware ensures all requests are formatted properly for a REST/JSON API. It requires that inbound requests meet all of the following conditions:
The request accepts application/json. The request's content type is application/json, if it has a body. The request is encoded in UTF-8. The request accepts UTF-8. The request is properly configured for CORS, if it requires it.
If any of these conditions is not met, Rest will respond with an appropriate HTTP error code and error message. Otherwise it will pass control down the line.
func Param ¶
Param retrieves a route param for the request by name, or the empty string if it cannot be found. For instance, on a request to "/users/jia/friends/bob" from a router handler with pattern string "/users/:userId/friends/:friendId", calling rest.Param with the following arguments would yield the following results:
rest.Param(ctx, "userId") // "jia" rest.Param(ctx, "friendId") // "bob" rest.Param(ctx, "enemyId") // ""
func ReadJSON ¶
ReadJSON reads the request body, parses its JSON, and stores it in the value pointed to by dst.
func WriteJSON ¶
func WriteJSON(w http.ResponseWriter, src interface{}) error
WriteJSON writes the JSON encoding of src to the response body. It also sets the response's status code appropriately.
As a special case, WriteJSON will automatically serialize error objects as JSON objects with a single field "message" holding the error text.
Error objects will get status codes based on their Code field.
All other objects implementing the error interface will get status code 500.
Types ¶
type Message ¶
type Message struct {
Message string `json:"message"`
}
Message wraps a string in a JSON object, which is the preferred error style for our API.
type Response ¶
type Response struct {
// Code is the http status code for the response.
Code int
// Body is the object to be serialized by encoding/json.
Body interface{}
}
Response is a wrapper for REST/JSON responses that permits you to set the status code and the response body all at once. Use it as follows:
rest.WriteJSON(w, rest.Response{http.StatusNoContent, &myObject})
It implements Error, so you can pass it around as an error interface.
func CreatedResponse ¶
func CreatedResponse(src interface{}) Response
CreatedResponse wraps a response object with http.StatusCreated for convenience.
Source Files