diff --git a/website/content/docs/concepts/api/http-api-model.mdx b/website/content/docs/api-clients/api.mdx similarity index 96% rename from website/content/docs/concepts/api/http-api-model.mdx rename to website/content/docs/api-clients/api.mdx index 949e2d6da5..0d652067bc 100644 --- a/website/content/docs/concepts/api/http-api-model.mdx +++ b/website/content/docs/api-clients/api.mdx @@ -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. diff --git a/website/content/docs/concepts/api/cli-behavior.mdx b/website/content/docs/api-clients/cli.mdx similarity index 90% rename from website/content/docs/concepts/api/cli-behavior.mdx rename to website/content/docs/api-clients/cli.mdx index 09fddc43a7..ba0220c833 100644 --- a/website/content/docs/concepts/api/cli-behavior.mdx +++ b/website/content/docs/api-clients/cli.mdx @@ -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. diff --git a/website/content/docs/developing/sdk/authenticate.mdx b/website/content/docs/api-clients/go-sdk.mdx similarity index 87% rename from website/content/docs/developing/sdk/authenticate.mdx rename to website/content/docs/api-clients/go-sdk.mdx index 73770f295f..3cf5b6736e 100644 --- a/website/content/docs/developing/sdk/authenticate.mdx +++ b/website/content/docs/api-clients/go-sdk.mdx @@ -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 diff --git a/website/content/docs/api-clients/index.mdx b/website/content/docs/api-clients/index.mdx new file mode 100644 index 0000000000..a89ff12ff0 --- /dev/null +++ b/website/content/docs/api-clients/index.mdx @@ -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. \ No newline at end of file diff --git a/website/content/docs/concepts/api/index.mdx b/website/content/docs/concepts/api/index.mdx deleted file mode 100644 index fe43e59eae..0000000000 --- a/website/content/docs/concepts/api/index.mdx +++ /dev/null @@ -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. diff --git a/website/content/docs/developing/sdk/index.mdx b/website/content/docs/developing/sdk/index.mdx deleted file mode 100644 index 4af474e5cb..0000000000 --- a/website/content/docs/developing/sdk/index.mdx +++ /dev/null @@ -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. diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 4fc13353ad..3d97b8d58b 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -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',