From c708e4d5dd303dd992b37dfa42f892b5b98510fc Mon Sep 17 00:00:00 2001
From: Thomas Eckert <teckert@hashicorp.com>
Date: Fri, 6 Jan 2023 16:10:56 -0500
Subject: [PATCH] Update the README for the Consul API (#15936)

---
 api/README.md | 56 ++++++++++++++++++++++++++++++---------------------
 1 file changed, 33 insertions(+), 23 deletions(-)

diff --git a/api/README.md b/api/README.md
index 3255cbb246..96a867f279 100644
--- a/api/README.md
+++ b/api/README.md
@@ -1,30 +1,36 @@
-Consul API client
-=================
+# Consul API Client
 
-This package provides the `api` package which attempts to
-provide programmatic access to the full Consul API.
+This package provides the `api` package which provides programmatic access to the full Consul API.
 
-Currently, all of the Consul APIs included in version 0.6.0 are supported.
+The full documentation is available on [Godoc](https://godoc.org/github.com/hashicorp/consul/api).
 
-Documentation
-=============
+## Usage
 
-The full documentation is available on [Godoc](https://godoc.org/github.com/hashicorp/consul/api)
+Below is an example of using the Consul client. To run the example, you must first
+[install Consul](https://developer.hashicorp.com/consul/downloads) and 
+[Go](https://go.dev/doc/install).
 
-Usage
-=====
+To run the client API, create a new Go module.
 
-Below is an example of using the Consul client:
+```shell
+go mod init consul-demo
+```
+
+Copy the example code into a file called `main.go` in the directory where the module is defined.
+As seen in the example, the Consul API is often imported with the alias `capi`.
 
 ```go
 package main
 
-import "github.com/hashicorp/consul/api"
-import "fmt"
+import (
+	"fmt"
+
+	capi "github.com/hashicorp/consul/api"
+)
 
 func main() {
 	// Get a new client
-	client, err := api.NewClient(api.DefaultConfig())
+	client, err := capi.NewClient(capi.DefaultConfig())
 	if err != nil {
 		panic(err)
 	}
@@ -33,7 +39,7 @@ func main() {
 	kv := client.KV()
 
 	// PUT a new KV pair
-	p := &api.KVPair{Key: "REDIS_MAXCLIENTS", Value: []byte("1000")}
+	p := &capi.KVPair{Key: "REDIS_MAXCLIENTS", Value: []byte("1000")}
 	_, err = kv.Put(p, nil)
 	if err != nil {
 		panic(err)
@@ -48,19 +54,23 @@ func main() {
 }
 ```
 
-To run this example, start a Consul server:
+Install the Consul API dependency with `go mod tidy`.
 
-```bash
-consul agent -dev
+In a separate terminal window, start a local Consul server.
+
+```shell
+consul agent -dev -node machine
 ```
 
-Copy the code above into a file such as `main.go`.
+Run the example.
 
-Install and run. You'll see a key (`REDIS_MAXCLIENTS`) and value (`1000`) printed.
+```shell
+go run .
+```
 
-```bash
-$ go get
-$ go run main.go
+You should get the following result printed to the terminal.
+
+```shell
 KV: REDIS_MAXCLIENTS 1000
 ```