Merge pull request #173 from waldyrious/doc-fixes

Various documentation fixes

LICENSE.md

@@ -1,3 +1,5 @@
+# MIT License
+
 Copyright 2020 Daniel G. Taylor
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

README.md

@@ -26,11 +26,11 @@ Features include:
   - OAuth2 authorization code (with PKCE [RFC 7636](https://tools.ietf.org/html/rfc7636)) flow
   - On the fly authorization through external tools for custom API signature mechanisms
 - 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/)
+  - 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)) and Brotli ([RFC 7932](https://tools.ietf.org/html/rfc7932)) content encoding
 - 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))

docs/.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

docs/README.md

@@ -35,11 +35,11 @@ Start with the [guide](/guide.md) to learn how to install and configure Restish
   - 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/)
+  - 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)) and Brotli ([RFC 7932](https://tools.ietf.org/html/rfc7932)) content encoding
 - 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))

docs/bulk.md

@@ -1,4 +1,4 @@
-# Bulk Resource Management
+# Bulk resource management
 
 Restish includes support for a `git`-like client-side bulk resource management interface, enabling you to pull resources onto disk and track both remote and local changes, get diffs, batch submit updates, etc.
 
@@ -10,7 +10,7 @@ If common response field names and standard conditional update headers are used,
 
 For example, you might have a simple CRUD-style API like this, which fully supports bulk operations:
 
-```
+```text
 GET    /books           List books returns [{url: "...", version: "..."}]
 GET    /books/{book-id} Get book
 PUT    /books/{book-id} Create/update book
@@ -19,7 +19,7 @@ DELETE /books/{book-id} Delete book
 
 ?> Resource creation via Restish `bulk` requires the use of client-generated identifiers and HTTP `PUT` requests. Use plain old `restish post ...` otherwise.
 
-## Getting Started & Demo
+## Getting started & demo
 
 Let's see how it works in action by using an example CRUD API:
 
@@ -57,7 +57,7 @@ $ rb list --match='author.lower contains brian'
 the-fabric-of-the-cosmos.json
 ```
 
-Restish also understands JSON Schema, so if the resources advertise a schema (e.g. via a `describedby` link relation of a `$schema` property) then it can provide useful errors when filtering. Since the example books advertise a schema at https://api.rest.sh/schemas/Book.json we can get warnings about potential expression problems:
+Restish also understands JSON Schema, so if the resources advertise a schema (e.g. via a `describedby` link relation of a `$schema` property) then it can provide useful errors when filtering. Since the example books advertise a schema at <https://api.rest.sh/schemas/Book.json> we can get warnings about potential expression problems:
 
 ```bash
 $ rb list --match='recent_ratings > 5'
@@ -137,7 +137,7 @@ Alias: `i`
 | `-f`, `--rsh-filter` | Filter the response via [Shorthand Query](./shorthand.md#querying)<br/>Example: `-f 'body.{id, version: last_modified_dt}'`                                                    |
 | `--url-template`     | Template string to build URLs from list response items. If a filter is passed, it is processed _before_ rendering the URL template.<br/>Example: `--url-template='/items/{id}` |
 
-#### Automatically Recognized Fields
+#### Automatically recognized fields
 
 The following fields are automatically recognized and used when available in the list response items, allowing bulk resource management to just work out of the box with a large number of APIs. Fields are checked in the order listed below and the first that is found will be used.
 
@@ -146,7 +146,7 @@ The following fields are automatically recognized and used when available in the
 | Resource URL     | `url`, `uri`, `self`, `link`                                   |
 | Resource version | `version`, `etag`, `last_modified`, `lastModified`, `modified` |
 
-#### Complex Example
+#### Complex example
 
 For a more complex example, let's assume you have an API at `example.com/items` which returns resources for multiple people via a list operation like this:
 

docs/comparison.md

@@ -31,7 +31,7 @@ See how Restish compares to other tools below:
 | Automatic pagination for `next` link relations       | ✅      | ❌            | ❌              |
 | URL & command shell completion hints                 | ✅      | ❌            | ❌              |
 
-# Performance Comparison
+## Performance comparison
 
 Test were run on a Macbook Pro and averages of several requests are reported as latency can and does vary. The general takeaway is that performance is better than HTTPie and very close to cURL but with many more features. Numbers below are in seconds.
 
@@ -66,9 +66,9 @@ time (repeat 10 {https https://httpbin.org/cache/60})
 time (repeat 10 {restish https://httpbin.org/cache/60})
 ```
 
-# Detailed Comparisons
+## Detailed comparisons
 
-## Passing Headers & Query Params
+### Passing headers & query parameters
 
 This is how you pass parameters to the API.
 
@@ -93,7 +93,7 @@ restish -H Header:value 'api.rest.sh/?a=1&b=true'
 restish -H Header:value api.rest.sh/ -q a=1 -q b=true
 ```
 
-## Input Shorthand
+### Input shorthand
 
 This is one mechanism to generate and pass a request body to the API.
 
@@ -124,7 +124,7 @@ restish post api.rest.sh \
   platform.apps: [Terminal, Desktop, Web, Mobile]
 ```
 
-## Getting Header Values
+### Getting header values
 
 How easy is it to read the output of a header in a shell environment?
 

docs/configuration.md

@@ -5,7 +5,7 @@ There are two types of configuration in Restish:
 1. Global configuration
 2. API-specific configuration
 
-## Global Configuration
+## Global configuration
 
 Global configuration affects all commands and can be set in one of three ways, going from highest to lowest precedence:
 
@@ -53,7 +53,7 @@ $ restish api.rest.sh/images
 
 Should TTY autodetection for colored output cause any problems, you can manually disable colored output via the `NOCOLOR=1` environment variable.
 
-## API Configuration
+## API configuration
 
 ### Adding an API
 
@@ -63,7 +63,7 @@ Adding or editing an API is possible via an interactive terminal UI:
 $ restish api configure $NAME [$BASE_URI]
 ```
 
-You should see something like the following, which enables you to create and edit profiles, headers, query params, and auth, eventually saving the data to `~/.restish/apis.json`:
+You should see something like the following, which enables you to create and edit profiles, headers, query parameters, and auth, eventually saving the data to `~/.restish/apis.json`:
 
 <img alt="Screen Shot" src="https://user-images.githubusercontent.com/106826/83099522-79dd3200-a062-11ea-8a78-b03a2fecf030.png">
 
@@ -105,9 +105,9 @@ $ restish api sync $NAME
 
 ?> This is usually not necessary, as Restish will update the API description every 24 hours. Use this if you want to force an update sooner!
 
-### Persistent Headers & Query Params
+### Persistent headers & query parameters
 
-Follow the prompts to add or edit persistent headers or query params. These are values that get sent with **every request** when using that profile.
+Follow the prompts to add or edit persistent headers or query parameters. These are values that get sent with **every request** when using that profile.
 
 Use cases:
 
@@ -136,7 +136,7 @@ Example:
 }
 ```
 
-### API Auth
+### API auth
 
 The following auth types are supported:
 
@@ -173,7 +173,7 @@ HTTP Basic Auth is sent via an `Authorization` HTTP header and requires a `usern
 
 #### API key
 
-API keys are values given to you by the API operator that identify you as the caller. There is no explicit auth support for API keys because they are already handled by persistend headers or query params.
+API keys are values given to you by the API operator that identify you as the caller. There is no explicit auth support for API keys because they are already handled by persistend headers or query parameters.
 
 For example, if your API operator has given you a JWT of `abc123`, you might set a persistent header like `Authorization: bearer abc123` in the default profile.
 
@@ -256,7 +256,7 @@ For example, to integrate with a third-party service like [Auth0](https://auth0.
 }
 ```
 
-#### External Tool
+#### External tool
 
 To allow interaction with APIs which have custom signature schemes, a
 third-party tool or script can be used. The script will need to accept
@@ -311,7 +311,7 @@ parameters only will be considered:
 - `uri`: Will replace the destination URL entirely (allowing the
   addition of query arguments if needed).
 
-### Loading From Files or URLs
+### Loading from files or URLs
 
 Sometimes an API won't provide a way to fetch its spec document, or a third-party will provide a spec for an existing public API, for example GitHub or Stripe.
 

docs/guide.md

@@ -29,7 +29,7 @@ $ restish --version
 
 ?> If using `zsh` as your shell (the default on macOS), you should set `alias restish="noglob restish"` in your `~/.zshrc` to prevent it from trying to handle `?` in URLs and `[]` in shorthand input. Alternatively you can use quotes around your inputs.
 
-## Basic Usage
+## Basic usage
 
 Generic HTTP verbs require no setup and are easy to use. If no verb is supplied then a GET is assumed. The `https://` is also optional as it is the default.
 
@@ -75,7 +75,7 @@ $ restish api.rest.sh/example
 
 !> Note that the output above is **not** JSON! By default, Restish outputs an HTTP+JSON-like format meant to be more readable. See [output](/output.md) for more info.
 
-### Input Parameters & Body
+### Input parameters & body
 
 Various inputs can be passed in as needed:
 
@@ -90,21 +90,21 @@ $ restish -H Accept:application/json api.rest.sh
 # Pass in a body via a file
 $ restish post api.rest.sh <input.json
 
-# Pass in body via CLI shorthand
+# Pass in body via CLI Shorthand
 $ restish post api.rest.sh name: Kari, tags[]: admin
 ```
 
-Read more about [CLI Shorthand](/shorthand.md). Headers and query params can also be set via environment variables by prefixing with `RSH_`, for example:
+Read more about [CLI Shorthand](/shorthand.md). Headers and query parameters can also be set via environment variables by prefixing with `RSH_`, for example:
 
 ```bash
 # Set via env vars
 $ export RSH_HEADER=header1:value1,header2:value2
 $ restish api.rest.sh
 ```
 
-?> If you have persistent headers or query params you'd like to set, then consider registering the API endpoint with Restish rather than exporting environment variables. Read on to find out how.
+?> If you have persistent headers or query parameters you'd like to set, then consider registering the API endpoint with Restish rather than exporting environment variables. Read on to find out how.
 
-### Editing Resources
+### Editing resources
 
 If an API supports both a `GET` and a `PUT` for a resource, there is a client-side `edit` convenience operation which allows you to edit the resource similar to how you might use a `PATCH` if the API were available.
 
@@ -120,7 +120,7 @@ To use interactive mode you must have the `VISUAL` or `EDITOR` environment varia
 
 Editing resources will make use of [conditional requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests) if any relevant headers are found on the `GET` response. For example, if an `ETag` header is present in the `GET` response then an `If-Match` header will be send on the `PUT` to prevent performing the write operation if the resource was modified by someone else while you are editing.
 
-### Output Filtering
+### Output filtering
 
 Restish includes built-in filtering using [Shorthand queries](shorthand.md#querying) which enable you to filter & project the response data. Using a filter only prints the result of the filter expression. Here are some basic examples:
 
@@ -157,7 +157,7 @@ Sat, 1 Jan 2022 12:00:00 GMT
 
 See [filtering & projection](output.md#filtering--projection) for more info & examples.
 
-### Output Defaults
+### Output defaults
 
 Like some other well-known tools, the output defaults are different depending on whether the command is running in an interactive shell or output is being redirected to a pipe or file.
 
@@ -171,7 +171,7 @@ See [output defaults](output.md#output-defaults) for more information.
 
 !> Use `restish api content-types` to see the avialable content types and output formats you can use.
 
-### Tabular Output
+### Tabular output
 
 Sometimes it's easier to read a response when you can see it in the form of a two-dimentional table. Restish supports the `table` output format for this purpose if the response (or filtered result) is an array of objects. For example:
 
@@ -192,7 +192,7 @@ Accept-Ranges: bytes
 ╚════════╧════════════════════════════╧══════════════╝
 ```
 
-## API Operation Commands
+## API-specific commands
 
 APIs can be registered in order to provide API description auto-discovery (e.g. OpenAPI 3) with convenience commands and authentication. The following API description formats and versions are supported:
 
@@ -206,7 +206,7 @@ APIs are registered with a short nickname. For example the GitHub v3 API might b
 
 Each registered API can have a number of named profiles which can be selected via the `-p` or `--rsh-profile` argument. The default profile is called `default`.
 
-Each profile can have a number of preset headers or query params, a type of auth, and any auth-specific params.
+Each profile can have a number of preset headers or query parameters, a type of auth, and any auth-specific parameters.
 
 Getting started registering an API is easy and uses an interactive prompt to set up profiles, auth, etc. At a minimum you must provide a short nickname and a base URL:
 
@@ -294,7 +294,7 @@ $ restish example get-image jpeg
 
 For more details, check out [OpenAPI](openapi.md).
 
-### Shell Command Line Completion
+### Shell command line completion
 
 Restish has support for dynamic shell completion built-in. See the help for your shell for how to enable this:
 

docs/hypermedia.md

@@ -11,7 +11,7 @@ Restish uses a standardized internal representation of hypermedia links to make
 
 The URI is always resolved so you don't need to worry about absolute or relative paths.
 
-## Automatic Pagination
+## Automatic pagination
 
 Restish uses these standardized links to automatically handle paginated collections, returning the full collection to you whenever possible.
 
@@ -69,9 +69,9 @@ Link: </images?cursor=abc123>; rel="next", </schemas/ImageItemList.json>; rel="d
 ]
 ```
 
-## Links Command
+## Links command
 
-The links command provides a shorthand for displaying the available links. All links are normalized to include the full URL. Paginated responses may generate the same link multiple times.
+The `links` command provides a shorthand for displaying the available links. All links are normalized to include the full URL. Paginated responses may generate the same link multiple times.
 
 ```bash
 # Display available links

docs/input.md

@@ -2,7 +2,7 @@
 
 You can set headers, query parameters, and a body for each outgoing request.
 
-## Request Parameters
+## Request parameters
 
 Request headers and query parameters are set via arguments or in the URI itself:
 
@@ -21,16 +21,16 @@ $ restish -H MyHeader:value api.rest.sh
 $ restish -H Header1:val1 -H Header2:val2 api.rest.sh
 ```
 
-?> Note that query params use `=` as a delimiter while haders use `:`, just like with HTTP.
+?> Note that query parameters use `=` as a delimiter while haders use `:`, just like with HTTP.
 
-## Request Body
+## Request body
 
 A request body can be set in two ways (or a combination of both) for requests that support bodies (e.g. `POST` / `PUT` / `PATCH`):
 
 1. Standard input
 2. CLI shorthand
 
-### Standard Input
+### Standard input
 
 Any stream of data passed to standard input will be sent as the request body.
 
@@ -46,7 +46,7 @@ $ echo '{"name": "hello"}' | restish put api.rest.sh
 
 ### CLI Shorthand
 
-The [CLI Shorthand](shorthand.md) is a convenient way of providing structured data on the commandline. It is a JSON-like syntax that enables you to easily create nested structured data. For example:
+The [CLI Shorthand](shorthand.md) language is a convenient way of providing structured data on the commandline. It is a JSON-like syntax that enables you to easily create nested structured data. For example:
 
 ```bash
 $ restish post api.rest.sh 'foo.bar[]{baz: 1, hello: world}'
@@ -73,7 +73,7 @@ Host: api.rest.sh
 
 The shorthand supports nested objects, arrays, automatic type coercion, and loading data from files. See the [CLI Shorthand Syntax](shorthand.md) for more info.
 
-### Combined Body Input
+### Combined body input
 
 It's also possible to use standard in as a template and replace or set values via commandline arguments, getting the best of both worlds. For example: