diff --git a/context.go b/context.go index c61a8085..7cf91b98 100644 --- a/context.go +++ b/context.go @@ -139,7 +139,7 @@ type ( // XMLPretty sends a pretty-print XML with status code. XMLPretty(code int, i interface{}, indent string) error - // XMLBlob sends a XML blob response with status code. + // XMLBlob sends an XML blob response with status code. XMLBlob(code int, b []byte) error // Blob sends a blob response with status code and content type. @@ -161,7 +161,7 @@ type ( // NoContent sends a response with no body and a status code. NoContent(code int) error - // Redirect redirects the request with status code. + // Redirect redirects the request to a provided URL with status code. Redirect(code int, url string) error // Error invokes the registered HTTP error handler. Generally used by middleware. diff --git a/website/content/guide/customization.md b/website/content/guide/customization.md index 77699b95..2ec825ab 100644 --- a/website/content/guide/customization.md +++ b/website/content/guide/customization.md @@ -21,7 +21,7 @@ You can set a custom HTTP error handler using `Echo#HTTPErrorHandler`. ## Debugging -`Echo#Debug` enable / disable debug mode. +`Echo#Debug` enable/disable debug mode. ## Logging diff --git a/website/content/guide/error-handling.md b/website/content/guide/error-handling.md index 9d76853b..925c50b6 100644 --- a/website/content/guide/error-handling.md +++ b/website/content/guide/error-handling.md @@ -8,10 +8,8 @@ description = "Error handling in Echo" +++ Echo advocates centralized HTTP error handling by returning error from middleware -or handlers. - -- Log errors from a unified location -- Send customized HTTP responses +and handlers. It allows us to log/report errors to external services from a unified +location and send customized HTTP responses. For example, when basic auth middleware finds invalid credentials it returns `401 - Unauthorized` error, aborting the current HTTP request. diff --git a/website/content/guide/response.md b/website/content/guide/response.md new file mode 100644 index 00000000..3f027fb3 --- /dev/null +++ b/website/content/guide/response.md @@ -0,0 +1,300 @@ ++++ +title = "Response" +description = "Sending HTTP response in Echo" +[menu.main] + name = "Response" + parent = "guide" + weight = 6 ++++ + +## Send String + +`Context#String(code int, s string)` can be used to send plain text response with status +code. + +*Example* + +```go +``` + +## Send HTML (Reference to templates) + +`Context#HTML(code int, html string)` can be used to send simple HTML response with +status code. If you are looking to send dynamically generate HTML see [templates](/guide/templates). + +*Example* + +```go +func(c echo.Context) error { + return c.HTML(http.StatusOK, "Hello, World!") +} +``` + +### Send HTML Blob + +`Context#HTMLBlob(code int, b []byte)` can be used to send HTML blob with status +code. You may find it handy using with a template engine which outputs `[]byte`. + +## Send JSON + +`Context#JSON(code int, i interface{})` can be used to encode a provided Go type into +JSON and send it as response with status code. + +*Example* + +```go +// User +type User struct { + Name string `json:"name" xml:"name"` + Email string `json:"email" xml:"email"` +} + +// Handler +func(c echo.Context) error { + u := &User{ + Name: "Jon", + Email: "jon@labstack.com", + } + return c.JSON(http.StatusOK, u) +} +``` + +### Stream JSON + +`Context#JSON()` internally uses `json.Marshal` which may not be efficient to large JSON, +in that case you can directly stream JSON. + +*Example* + +```go +func(c echo.Context) error { + u := &User{ + Name: "Jon", + Email: "jon@labstack.com", + } + c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationJSONCharsetUTF8) + c.Response().WriteHeader(http.StatusOK) + return json.NewEncoder(c.Response()).Encode(u) +} +``` + +### JSON Pretty + +`Context#JSONPretty(code int, i interface{}, indent string)` can be used to a send +a JSON response which is pretty printed based on indent, which could spaces or tabs. + +Example below sends a pretty print JSON indented with spaces: + +```go +func(c echo.Context) error { + u := &User{ + Name: "Jon", + Email: "joe@labstack.com", + } + return c.JSONPretty(http.StatusOK, u, " ") +} +``` + +```js +{ + "email": "joe@labstack.com", + "name": "Jon" +} +``` + +### JSON Blob + +`Context#JSONBlob(code int, b []byte)` can be used to send pre-encoded JSON blob directly +from external source, for example, database. + +*Example* + +```go +func(c echo.Context) error { + encodedJSON := []byte{} // Encoded JSON from external source + return c.JSONBlob(http.StatusOK, encodedJSON) +} +``` + +## Send JSONP + +`Context#JSONP(code int, callback string, i interface{})` can be used to encode a provided +Go type into JSON and send it as JSONP payload constructed using a callback, with +status code. + +[*Example*](/recipes/jsonp) + +## Send XML + +`Context#XML(code int, i interface{})` can be used to encode a provided Go type into +XML and send it as response with status cod. + +*Example* + +```go +func(c echo.Context) error { + u := &User{ + Name: "Jon", + Email: "jon@labstack.com", + } + return c.XML(http.StatusOK, u) +} +``` + +### Stream XML + +`Context#XML` internally uses `xml.Marshal` which may not be efficient to large XML, +in that case you can directly stream XML. + +*Example* + +```go +func(c echo.Context) error { + u := &User{ + Name: "Jon", + Email: "jon@labstack.com", + } + c.Response().Header().Set(echo.HeaderContentType, echo.MIMEApplicationXMLCharsetUTF8) + c.Response().WriteHeader(http.StatusOK) + return xml.NewEncoder(c.Response()).Encode(u) +} +``` + +### XML Pretty + +`Context#XMLPretty(code int, i interface{}, indent string)` can be used to a send +an XML response which is pretty printed based on indent, which could spaces or tabs. + +Example below sends a pretty print XML indented with spaces: + +```go +func(c echo.Context) error { + u := &User{ + Name: "Jon", + Email: "joe@labstack.com", + } + return c.XMLPretty(http.StatusOK, u, " ") +} +``` + +```xml + + + Jon + joe@labstack.com + +``` + +### XML Blob + +`Context#XMLBlob(code int, b []byte)` can be used to send pre-encoded XML blob directly +from external source, for example, database. + +*Example* + +```go +func(c echo.Context) error { + encodedXML := []byte{} // Encoded XML from external source + return c.XMLBlob(http.StatusOK, encodedXML) +} +``` + +## Send File + +`Context#File(file string)` can be used to send the content of file as response. +It automatically sets the correct content type and handles caching gracefully. + +*Example* + +```go +func(c echo.Context) error { + return c.File("") +} +``` + +## Send Attachment + +`Context#Attachment(file, name string)` is similar to `File()` except that it is +used to send file as attachment with provided name. + +*Example* + +```go +func(c echo.Context) error { + return c.Attachment("") +} +``` + +## Send Inline + +`Context#Inline(file, name string)` is similar to `File()` except that it is +used to send file as inline with provided name. + +*Example* + +```go +func(c echo.Context) error { + return c.Inline("") +} +``` + +## Send Blob + +`Context#Blob(code int, contentType string, b []byte)` can be used to send an arbitrary +data response with provided content type and status code. + +*Example* + +```go +func(c echo.Context) (err error) { + data := []byte(`0306703,0035866,NO_ACTION,06/19/2006 + 0086003,"0005866",UPDATED,06/19/2006`) + return c.Blob(http.StatusOK, "text/csv", data) +} +``` + +// Stream sends a streaming response with status code and content type. + Stream(code int, contentType string, r io.Reader) error + +## Send Stream + +`Context#Stream(code int, contentType string, r io.Reader)` can be used to send an +arbitrary data stream response with provided content type, `io.Reader` and status +code. + +*Example* + +```go +func(c echo.Context) error { + f, err := os.Open("") + if err != nil { + return err + } + return c.Stream(http.StatusOK, "image/png", f) +} +``` + +## Send No Content + +`Context#NoContent(code int)` can be used to send empty body with status code. + +*Example* + +```go +func(c echo.Context) error { + return c.NoContent(http.StatusOK) +} +``` + +## Redirect Request + +`Context#Redirect(code int, url string)` can be used to redirect the request to +a provided URL with status code. + +*Example* + +```go +func(c echo.Context) error { + return c.Redirect(http.StatusMovedPermanently, "") +} +``` diff --git a/website/content/recipes/auto-tls.md b/website/content/recipes/auto-tls.md index 6493ba26..3e4b4b6e 100644 --- a/website/content/recipes/auto-tls.md +++ b/website/content/recipes/auto-tls.md @@ -10,7 +10,7 @@ description = "Automatic TLS certificates from Let's Encrypt example for Echo" This recipe shows how to obtain TLS certificates for a domain automatically from Let's Encrypt. `Echo#StartAutoTLS` accepts an address which should listen on port `443`. -Browse to `https://`. If everything goes fine, you should see a welcome +Browse to `https://`. If everything goes fine, you should see a welcome message with TLS enabled on the website. >