fix: guide v1 api configure users to v2

Author: danielgtaylor

internal/cli/api.go

@@ -75,6 +75,15 @@ func (c *CLI) addAPICommand(root *cobra.Command) {
 	connectCmd.Flags().Bool("replace", false, "Replace existing profiles with discovered OpenAPI/x-cli-config defaults")
 	connectCmd.Flags().Bool("yes", false, "Accept safe api connect prompts without asking")
 	apiCmd.AddCommand(connectCmd)
+	apiCmd.AddCommand(&cobra.Command{
+		Use:                "configure <name> [url]",
+		Short:              "Explain the v1 api configure replacement",
+		Hidden:             true,
+		DisableFlagParsing: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return newUsageError(c.apiConfigureMigrationError(args))
+		},
+	})
 	apiCmd.AddCommand(&cobra.Command{
 		Use:     "inspect <name>",
 		Short:   "Print the config for a registered API as JSON",
@@ -94,6 +103,28 @@ func (c *CLI) addAPICommand(root *cobra.Command) {
 	root.AddCommand(apiCmd)
 }
 
+func (c *CLI) apiConfigureMigrationError(args []string) error {
+	commandName := c.commandNameOrDefault()
+	replacement := fmt.Sprintf("  %s api connect <name> <url>", commandName)
+	if len(args) == 1 && !strings.HasPrefix(args[0], "-") {
+		replacement = fmt.Sprintf("  %s api connect %s <url>", commandName, args[0])
+	} else if len(args) >= 2 && !strings.HasPrefix(args[0], "-") && !strings.HasPrefix(args[1], "-") {
+		replacement = fmt.Sprintf("  %s api connect %s %s", commandName, args[0], args[1])
+	}
+	return fmt.Errorf(`api configure was a Restish v1 command and is not available in v2.
+
+Use api connect to register an API explicitly:
+
+%s
+
+In many cases replacing "configure" with "connect" is enough. If the v1
+command prompted for auth, profiles, or other defaults, connect first and then
+adjust the API with "restish api set".
+
+Upgrade guide: https://rest.sh/docs/getting-started/upgrade-from-v1/
+Archived v1 docs: https://rest.sh/v1/`, replacement)
+}
+
 // runAPIAuthLogout deletes the token cache entry for the named API+profile.
 func (c *CLI) runAPIAuthLogout(cmd *cobra.Command, args []string) error {
 	authProfile, _ := cmd.Flags().GetString("auth-profile")

internal/cli/api_manage_test.go

@@ -2641,7 +2641,6 @@ func TestAPIConnectAdversarialSpecShapesFailGracefully(t *testing.T) {
 func TestAPIConnectRejectsRemovedCommandNames(t *testing.T) {
 	for _, args := range [][]string{
 		{"restish", "api", "add", "myapi", "https://api.example.com"},
-		{"restish", "api", "configure", "myapi", "https://api.example.com"},
 		{"restish", "api", "delete", "myapi"},
 	} {
 		c, _, _ := newTestCLI(t)
@@ -2653,6 +2652,20 @@ func TestAPIConnectRejectsRemovedCommandNames(t *testing.T) {
 	}
 }
 
+func TestAPIConfigureShowsV1MigrationMessage(t *testing.T) {
+	c, _, _ := newTestCLI(t)
+	err := c.Run([]string{"restish", "api", "configure", "myapi", "https://api.example.com"})
+	if err == nil {
+		t.Fatal("api configure should fail with a v1 migration message")
+	}
+	requireContains(t, err.Error(),
+		"api configure was a Restish v1 command",
+		"restish api connect myapi https://api.example.com",
+		"https://rest.sh/docs/getting-started/upgrade-from-v1/",
+		"https://rest.sh/v1/",
+	)
+}
+
 func TestAPIRemovePreservesJSONCComments(t *testing.T) {
 	cfgFile := writeAPIConfig(t, `{
   "apis": {

site/content/en/docs/getting-started/_index.md

@@ -35,7 +35,7 @@ locally.
 
 ## Existing v1 Users
 
-If you already have Restish v1 config or plugins, read [Upgrade From v1](./upgrade-from-v1/) before editing config. The migration docs are kept out of the new-user happy path, but they are still important for existing setups.
+If you already have Restish v1 config or plugins, read [Upgrade From v1](./upgrade-from-v1/) before editing config. The migration docs are kept out of the new-user happy path, but they are still important for existing setups. The archived v1 docs remain available at [rest.sh/v1/](https://rest.sh/v1/).
 
 ## Related Pages
 

site/content/en/docs/getting-started/install.md

@@ -89,7 +89,9 @@ Use `bash` or `fish` instead of `zsh` when that is your shell.
 
 Restish v2 can migrate default-location v1 config on first run. Read
 [Upgrade From v1](../upgrade-from-v1/) before editing config or replacing
-plugins.
+plugins. The archived v1 documentation remains available at
+[rest.sh/v1/](https://rest.sh/v1/) for teams that need to compare old commands during a
+migration.
 
 ## Next Step
 
@@ -104,3 +106,4 @@ next to see the major workflows before connecting your own APIs.
 - [Shell Setup](../shell-setup/)
 - [Development Setup](/docs/contributing/development-setup/)
 - [Upgrade From v1](../upgrade-from-v1/)
+- [Archived v1 Docs](https://rest.sh/v1/)

site/content/en/docs/getting-started/upgrade-from-v1.md

@@ -9,6 +9,8 @@ aliases:
 
 This page is the shortest path for existing Restish v1 users who want to know
 what changed, what is preserved automatically, and what needs a manual update.
+The archived v1 documentation remains available at [rest.sh/v1/](https://rest.sh/v1/) for
+old links, internal runbooks, and side-by-side migration checks.
 
 ## What To Expect
 
@@ -115,6 +117,7 @@ Use this as the fast lookup table when muscle memory collides with v2.
 | ------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
 | `apis.json`                           | `restish.json`                                              | API config now lives under top-level `apis`           |
 | `config.json`                         | `restish.json`                                              | v2 uses one config file                               |
+| `restish api configure <name> <url>`  | `restish api connect <name> <url>`                          | v2 prints a migration hint for `api configure`        |
 | `restish api edit`                    | `restish config edit`                                       | Config editing moved under `config`                   |
 | old interactive API setup             | `restish api connect <name> <url>`                          | v2 expects the base URL explicitly                    |
 | n/a                                   | `restish api connect <name> <url> 'path:value'`             | fast one-shot registration with shorthand expressions |
@@ -185,3 +188,4 @@ restish config edit
 - [Tour of Restish](../tour/)
 - [Config](/docs/reference/config/)
 - [Install And Use Plugins](/docs/plugins/install-and-use/)
+- [Archived v1 Docs](https://rest.sh/v1/)

site/layouts/_partials/hooks/body-end.html

@@ -1,2 +1,9 @@
 <script src='{{ "js/prism-restish.js" | relURL }}'></script>
 <script src='{{ "js/restish-playground.js" | relURL }}'></script>
+<script>
+  (function () {
+    if (window.location.pathname === "/" && window.location.hash.indexOf("#/") === 0) {
+      window.location.replace("/v1/" + window.location.hash);
+    }
+  }());
+</script>

site/static/v1/.markdownlint.yaml

@@ -0,0 +1,13 @@
+default: true
+
+# no-hard-tabs
+MD010: false
+
+# line-length
+MD013: false
+
+# commands-show-output
+MD014: false
+
+# no-inline-html
+MD033: false

site/static/v1/.nojekyll

@@ -0,0 +1,61 @@
+![Restish Logo](https://user-images.githubusercontent.com/106826/82109918-ec5b2300-96ee-11ea-9af0-8515329d5965.png)
+
+<div style="text-align: center;">
+
+[![Works With Restish](https://img.shields.io/badge/Works%20With-Restish-ff5f87)](https://rest.sh/) [![User Guide](https://img.shields.io/badge/Docs-Guide-5fafd7)](https://rest.sh/v1/#/guide) [![CI](https://github.com/rest-sh/restish/workflows/CI/badge.svg?branch=main)](https://github.com/rest-sh/restish/actions?query=workflow%3ACI+branch%3Amain++) [![codecov](https://codecov.io/gh/rest-sh/restish/branch/main/graph/badge.svg)](https://codecov.io/gh/rest-sh/restish) [![Docs](https://img.shields.io/badge/godoc-reference-5fafd7)](https://pkg.go.dev/github.com/rest-sh/restish?tab=subdirectories) [![Go Report Card](https://goreportcard.com/badge/github.com/rest-sh/restish)](https://goreportcard.com/report/github.com/rest-sh/restish) [![GitHub Likes](https://img.shields.io/github/stars/rest-sh/restish?style=social)](https://github.com/rest-sh/restish)
+
+</div>
+
+[Restish](https://rest.sh/) is a CLI for interacting with [REST](https://apisyouwonthate.com/blog/rest-and-hypermedia-in-2019)-ish HTTP APIs with some nice features built-in, like always having the latest API resources, fields, and operations available when they go live on the API without needing to install or update anything.
+
+## Why use this?
+
+Every API deserves a CLI for quick access and for power users to script against the service. Building CLIs from scratch is a pain. Restish provides one tool your users can install that just works for multiple APIs and is always up to date, because the interface is defined by the server. See how it [compares](./comparison.md) to cURL and HTTPie.
+
+## Getting started
+
+Start with the [guide](./guide.md) to learn how to install and configure Restish as well as getting an overview of all of its features.
+
+## Features
+
+- HTTP/2 ([RFC 7540](https://tools.ietf.org/html/rfc7540)) with TLS by _default_ with fallback to HTTP/1.1
+- Generic HEAD/GET/POST/PUT/PATCH/DELETE verbs like `curl` or [HTTPie](https://httpie.org/)
+- Generated commands for CLI operations, e.g. `restish my-api list-users`
+  - Automatically discovers API descriptions
+    - [RFC 8631](https://tools.ietf.org/html/rfc8631) `service-desc` link relation
+    - [RFC 5988](https://tools.ietf.org/html/rfc5988#section-6.2.2) `describedby` link relation
+  - Supported formats
+    - OpenAPI [3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md) / [3.1](https://spec.openapis.org/oas/v3.1.0.html) and [JSON Schema](https://json-schema.org/)
+  - Automatic configuration of API auth if advertised by the API
+  - Shell command completion for Bash, Fish, Zsh, Powershell
+- Automatic pagination of resource collections via [RFC 5988](https://tools.ietf.org/html/rfc5988) `prev` and `next` hypermedia links
+- API endpoint-based auth built-in with support for profiles:
+  - HTTP Basic
+  - API key via header or query param
+  - OAuth2 client credentials flow (machine-to-machine, [RFC 6749](https://tools.ietf.org/html/rfc6749))
+  - OAuth2 authorization code (with PKCE [RFC 7636](https://tools.ietf.org/html/rfc7636)) flow
+- Content negotiation, decoding & unmarshalling built-in:
+  - JSON ([RFC 8259](https://tools.ietf.org/html/rfc8259), <https://www.json.org/>)
+  - YAML (<https://yaml.org/>)
+  - CBOR ([RFC 7049](https://tools.ietf.org/html/rfc7049), <http://cbor.io/>)
+  - MessagePack (<https://msgpack.org/>)
+  - Amazon Ion (<http://amzn.github.io/ion-docs/>)
+  - Gzip ([RFC 1952](https://tools.ietf.org/html/rfc1952)), Deflate ([RFC 1951](https://datatracker.ietf.org/doc/html/rfc1951)), and Brotli ([RFC 7932](https://tools.ietf.org/html/rfc7932)) content encoding
+- Automatic retries with support for [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) and `X-Retry-In` headers when APIs are rate-limited.
+- Standardized [hypermedia](https://smartbear.com/learn/api-design/what-is-hypermedia/) parsing into queryable/followable response links:
+  - HTTP Link relation headers ([RFC 5988](https://tools.ietf.org/html/rfc5988#section-6.2.2))
+  - [HAL](http://stateless.co/hal_specification.html)
+  - [Siren](https://github.com/kevinswiber/siren)
+  - [Terrifically Simple JSON](https://github.com/mpnally/Terrifically-Simple-JSON)
+  - [JSON:API](https://jsonapi.org/)
+- Local caching that respects [RFC 7234](https://tools.ietf.org/html/rfc7234) `Cache-Control` and `Expires` headers
+- Client-side bulk resource management (like git for API resources)
+- CLI [shorthand](https://github.com/danielgtaylor/openapi-cli-generator/tree/master/shorthand#cli-shorthand-syntax) for structured data input (e.g. for JSON)
+- [Shorthand query](https://github.com/danielgtaylor/shorthand#querying) response filtering & projection
+- Colorized prettified readable output
+- Fast native zero-dependency binary
+
+## Articles
+
+- [A CLI for REST APIs](https://dev.to/danielgtaylor/a-cli-for-rest-apis-part-1-104b)
+- [Mapping OpenAPI to the CLI](https://dev.to/danielgtaylor/mapping-openapi-to-the-cli-37pb)

site/static/v1/README.md

@@ -0,0 +1,11 @@
+- [Home](./ "Restish")
+- [Guide](guide.md "Restish User Guide")
+- [Comparison](comparison.md "Comparison")
+- [Configuration](configuration.md "Configuring Restish")
+- [OpenAPI](openapi.md "OpenAPI 3 & Restish")
+- [Input](input.md "Restish Input")
+- [CLI Shorthand](shorthand.md "CLI Shorthand")
+- [Output](output.md "Restish Output")
+- [Retries & Timeouts](retries.md "Retries & Timeouts")
+- [Hypermedia](hypermedia.md "Hypermedia Linking in Restish")
+- [Bulk Management](bulk.md "Bulk Resource Management")