Consolidate client/API information to a new section (#630)

2020-10-12 14:46:17 -04:00
1 parent 837e9eb0cc
commit e162f9f183
@@ -1,14 +1,14 @@
 ---
 layout: docs
-page_title: HTTP API Standards
-sidebar_title: HTTP API Standards
+page_title: API
+sidebar_title: API
 description: |-
  Boundary's HTTP API standards
 ---

-# HTTP API Standards 
+# API

-Boundary's HTTP API adheres to a set of standards that are rigidly followed. At its core, it is a standards-compliant JSON API for both input and output.
+Boundary's API is a a JSON-based HTTP API that adheres to a set of standards that are rigidly followed. At its core, it is a standards-compliant JSON API for both input and output.

 Before reading this page, it is useful to understand Boundary's [domain model](/docs/concetps/domain-model) to be aware of the terminology used here.

@@ -1,15 +1,27 @@
 ---
 layout: docs
-page_title: CLI Behavior
-sidebar_title: CLI Behavior
+page_title: CLI
+sidebar_title: CLI
 description: |-
  Boundary's CLI behavior
 ---

-# CLI Behavior
+# CLI

 Boundary's CLI has predictable behavior throughout its various commands. This page details the common patterns in used in order to help users make better use of the CLI.

+## Completion
+
+Before detailing how parameters work, it's useful to note that Boundary's CLI supports autocompletion, which allows tab completion of commands, flags, and in some cases the parameters to those flags.
+
+This can be installed via the CLI itself:
+
+`boundary config autocomplete install`
+
+If you want to install it manually, for Bash, the following line in a `~/.bash_profile` or similar file will work:
+
+`complete -C /path/to/boundary boundary`
+
 ## Parameter Handling

 All parameters specified on the CLI are specified as a Go-style flag with a single dash, e.g. `-id`. The arguments to those flags can be specified via an equals sign, as in `-id=r_1234567890`, or a space, like `-id r_1234567890`.
@@ -70,11 +82,3 @@ However, a target can be one of many types of targets, and a concrete implementa
 This allows the CLI to perform proper presentation and validation of parameters and functions for the given type.

 Similar to `read`, `update` operates on an existing target so will always take an `-id` parameter. Similar to `list`, `create` operates on a collection so will either take a `-scope-id` parameter or a parameter defining the parent resource.
-
-## Completion
-
-Boundary's CLI supports autocompletion. For Bash, the following line in a `~/.bash_profile` or similar file will work:
-
-`complete -C /path/to/boundary boundary`
-
-This will allow tab completion of commands, flags, and in some cases the parameters to those flags.
@@ -1,12 +1,18 @@
 ---
 layout: docs
-page_title: SDK - Authenticate
-sidebar_title: Authenticate
+page_title: Go SDK
+sidebar_title: Go SDK
 description: |-
-  Boundary SDK authenticate 
+  Boundary's Go SDK
 ---

-# Authenticate 
+# Go SDK
+
+Boundary has a Go SDK that sports full coverage of Boundary's API. This SDK is mostly auto-generated so the patterns are predictable from package to package; for the most part, browsing [pkg.go.dev](https://pkg.go.dev/github.com/hashicorp/boundary/api) is a great way to get started.
+
+Below, an example walks through using the SDK to authenticate against an auth method or perform recovery workflows. The patterns for creating a resource-typed client are the same across packages.
+
+## Authenticating to Boundary with the Go SDK

 Authenticating to Boundary starts with an [Auth Method](/docs/concepts/domain-model/auth-methods). An auth method provides
 the basic identity delegation needed for Boundary to generate a token for a client. There are two primary methods for
@@ -17,7 +23,7 @@ authenticating to Boundary:

 We'll cover how to authenticate to Boundary via both of these workflows. 

-## Authentication Method
+### Authentication Method

 This is the most common way for a client to authenticate to Boundary. To demonstrate this, we'll
 use the [authmethods](https://github.com/hashicorp/boundary/tree/main/api/authmethods) library to generate
@@ -31,7 +37,7 @@ method, login name, and password are pre-configured.

 First, we need to create a client from the Boundary API and set the address to reach Boundary:

-```golang
+```go
 import github.com/boundary/api

 // The default address points to the default dev mode address
@@ -48,7 +54,7 @@ to eventually support multiple auth method types. For this example, we assume
 you're using the password auth method and so we're going to tailor a credentials
 object to pass this data as:

-```golang
+```go
 credentials := map[string]interface{}{
  "login_name": "admin",
  "password":   "password",
@@ -57,7 +63,7 @@ credentials := map[string]interface{}{

 Now let's create an auth method client using the base client from above:

-```golang
+```go
 import "github.com/boundary/api/authmethods"

 am := authmethods.NewClient(client)
@@ -83,7 +89,7 @@ Note the ID in the output above, we're going to use that in the next step.

 We can use the credentials object we created to execute `Authenticate()` on this client:

-```golang
+```go
 at, err := am.Authenticate(context.Background(), "ampw_1234567890", credentials)
 if err != nil {
  return err
@@ -92,14 +98,14 @@ if err != nil {

 Lastly, let's update the original client with the token we got from the `Authenticate()` call:

-```golang
+```go
 // pass this client to any other resource specific API resources
 client.SetToken(at.Item.Token)
 ```

 Putting this all together:

-```golang
+```go
 import (
  github.com/boundary/api
  github.com/boundary/api/authmethods
@@ -126,7 +132,7 @@ if err != nil {
 client.SetToken(at.Item.Token)
 ```

-## Recovery KMS Workflow
+### Recovery KMS Workflow

 The recovery KMS workflow allows you to use a valid [KMS
 configuration](/docs/configuration/kms) to authenticate and authorize calls
@@ -138,7 +144,7 @@ AEAD key as the basis. To authenticate with Boundary using this config we're
 assuming you have an instance of Boundary that declares this as the recovery KMS
 in the Boundary controller config as well.

-```golang
+```go
 import "github.com/hashicorp/boundary/sdk/wrapper"

 const kmsConfig := `
@@ -153,7 +159,7 @@ kms "aead" {

 Now lets use this config to configure our Boundary API client:

-```golang
+```go
 w, err := wrapper.GetWrapperFromHcl(kmsConfig, "recovery")
 if err != nil {
  return err
@@ -0,0 +1,14 @@
+---
+layout: docs
+page_title: API/Clients
+sidebar_title: API/Clients
+description: |-
+  An introduction to Boundary's API and clients.
+---
+
+
+# Clients
+
+Boundary is a purely-API-driven system. This section contains information
+describing its API norms and the clients that HashiCorp provide (apart from the
+web UI), which include a CLI and a Go SDK.
@@ -1,12 +0,0 @@
---
-layout: docs
-page_title: API
-sidebar_title: API
-description: |-
-  An introduction to Boundary's API.
---
-
-# Boundary API
-
-This section covers our API, including information about its underlying model
-and how the CLI implements support for the API.
@@ -1,19 +0,0 @@
---
-layout: docs
-page_title: SDK
-sidebar_title: SDK
-description: |-
-  Reference documentation for the Boundary SDK
---
-
-# Overview
-
-The Boundary SDK is written in Go and the reference documentation here assumes basic Go experience including a local 
-environment for developing Go code bases.
-
-## Getting Started
-
-Download the latest `main` branch revision of our [project on GitHub](https://github.com/hashicorp/boundary). 
-
-As a developer, the most common package within this project that you'll interact is our [API package](https://github.com/hashicorp/boundary/tree/main/api). 
-This package contains all the common client libraries that you'll need to interact with the Boundary platform. 
@@ -16,23 +16,12 @@ export default [
    content: ['systemd', 'postgres', 'high-availability'],
  },
  {
-    category: 'developing',
-    content: [
-      'building',
-      'ui',
-      {
-        category: 'sdk',
-        content: ['authenticate'],
-      },
-    ],
+    category: 'api-clients',
+    content: ['api', 'cli', 'go-sdk'],
  },
  {
    category: 'concepts',
    content: [
-      {
-        category: 'api',
-        content: ['http-api-model', 'cli-behavior'],
-      },
      {
        category: 'security',
        content: [
@@ -59,6 +48,13 @@ export default [
      },
    ],
  },
+  {
+    category: 'developing',
+    content: [
+      'building',
+      'ui',
+    ],
+  },
  '---',
  {
    category: 'configuration',