rest: Add godoc example test for client.

- Update README and CHANGELOG

CHANGELOG.md

@@ -11,10 +11,16 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Use Go 1.11 modules for reproducible builds.
 - SMTP TLS support (thanks kingforaday.)
 - `INBUCKET_WEB_PPROF` configuration option for performance profiling.
+- Godoc example for the REST API client.
 
 ### Changed
 - Docker build now uses Go 1.11 and Alpine 3.8
 
+### Fixed
+- Render UTF-8 addresses correctly in both REST API and Web UI.
+- Memory storage now correctly returns the newest message when asked for ID
+  `latest`.
+
 
 ## [v2.0.0] - 2018-05-05
 

README.md

@@ -7,6 +7,9 @@ address and make them available via web, REST and POP3.  Once compiled,
 Inbucket does not have any external dependencies (HTTP, SMTP, POP3 and storage
 are all built in).
 
+A Go client for the REST API is available in
+`github.com/jhillyerd/inbucket/pkg/rest/client` - [Go API docs]
+
 Read more at the [Inbucket Website]
 
 ![Screenshot](http://www.inbucket.org/images/inbucket-ss1.png "Viewing a message")
@@ -55,6 +58,7 @@ Inbucket is written in [Google Go]
 Inbucket is open source software released under the MIT License.  The latest
 version can be found at https://github.com/jhillyerd/inbucket
 
+[Go API docs]:      https://godoc.org/github.com/jhillyerd/inbucket/pkg/rest/client
 [Build Status]:     https://travis-ci.org/jhillyerd/inbucket
 [Change Log]:       https://github.com/jhillyerd/inbucket/blob/master/CHANGELOG.md
 [CONTRIBUTING.md]:  https://github.com/jhillyerd/inbucket/blob/develop/CONTRIBUTING.md

pkg/rest/client/example_test.go

@@ -0,0 +1,102 @@
+package client_test
+
+import (
+	"fmt"
+	"log"
+	"net/http"
+	"net/http/httptest"
+
+	"github.com/gorilla/mux"
+	"github.com/jhillyerd/inbucket/pkg/rest/client"
+)
+
+// Example demonstrates basic usage for the Inbucket REST client.
+func Example() {
+	// Setup a fake Inbucket server for this example.
+	baseURL, teardown := exampleSetup()
+	defer teardown()
+
+	// Begin by creating a new client using the base URL of your Inbucket server, i.e.
+	// `localhost:9000`.
+	restClient, err := client.New(baseURL)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Get a slice of message headers for the mailbox named `user1`.
+	headers, err := restClient.ListMailbox("user1")
+	if err != nil {
+		log.Fatal(err)
+	}
+	for _, header := range headers {
+		fmt.Printf("ID: %v, Subject: %v\n", header.ID, header.Subject)
+	}
+
+	// Get the content of the first message.
+	message, err := headers[0].GetMessage()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("\nFrom: %v\n", message.From)
+	fmt.Printf("Text body:\n%v", message.Body.Text)
+
+	// Delete the second message.
+	err = headers[1].Delete()
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Output:
+	// ID: 20180107T224128-0000, Subject: First subject
+	// ID: 20180108T121212-0123, Subject: Second subject
+	//
+	// From: admin@inbucket.org
+	// Text body:
+	// This is the plain text body
+}
+
+// exampleSetup creates a fake Inbucket server to power Example() below.
+func exampleSetup() (baseURL string, teardown func()) {
+	router := mux.NewRouter()
+	server := httptest.NewServer(router)
+
+	// Handle ListMailbox request.
+	router.HandleFunc("/api/v1/mailbox/user1", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`[
+			{
+				"mailbox": "user1",
+				"id": "20180107T224128-0000",
+				"subject": "First subject"
+			},
+			{
+				"mailbox": "user1",
+				"id": "20180108T121212-0123",
+				"subject": "Second subject"
+			}
+		]`))
+	})
+
+	// Handle GetMessage request.
+	router.HandleFunc("/api/v1/mailbox/user1/20180107T224128-0000",
+		func(w http.ResponseWriter, r *http.Request) {
+			w.Write([]byte(`{
+				"mailbox": "user1",
+				"id": "20180107T224128-0000",
+				"from": "admin@inbucket.org",
+				"subject": "First subject",
+				"body": {
+					"text": "This is the plain text body"
+				}
+			}`))
+		})
+
+	// Handle Delete request.
+	router.HandleFunc("/api/v1/mailbox/user1/20180108T121212-0123",
+		func(w http.ResponseWriter, r *http.Request) {
+			// Nop.
+		})
+
+	return server.URL, func() {
+		server.Close()
+	}
+}