Add API reference to docs

README.md

@@ -7,7 +7,7 @@
 
 Slumber is a TUI (terminal user interface) REST client. Define, execute, and share configurable HTTP requests.
 
-## Example
+## Examples
 
 Slumber is based around **collections**. A collection is a group of request **recipes**, which are templates for the requests you want to run. A simple collection could be:
 

docs/src/SUMMARY.md

@@ -1,3 +1,16 @@
 # Summary
 
-- [Quick Start](./quick_start.md)
+[Quick Start](./quick_start.md)
+
+# User Guide
+
+- [User Guide](./user_guide.md)
+
+# API Reference
+
+- [Request Collection](./api/request_collection.md)
+  - [Profile](./api/profile.md)
+  - [Request Recipe](./api/request_recipe.md)
+  - [Chain](./api/chain.md)
+  - [Chain Source](./api/chain_source.md)
+  - [Template String](./api/template_string.md)

docs/src/api/chain.md

@@ -0,0 +1,35 @@
+# Chain
+
+A chain is a intermediate data type to enable complex template values. Chains enable complex value sources and additional customization, such as much values as sensitive to be masked in the UI.
+
+To use a chain in a template string, reference it as `{{chains.<id>}}`.
+
+## Fields
+
+| Field       | Type                                                                                   | Description                                             | Default  |
+| ----------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------- | -------- |
+| `id`        | `string`                                                                               | Unique identifier for this chain                        | Required |
+| `source`    | [`ChainSource`](./chain_source.md)                                                     | Source of the chained value                             | Required |
+| `sensitive` | `boolean`                                                                              | Should the value be hidden in the UI?                   | `false`  |
+| `selector`  | [`JSONPath`](https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html) | Selector to narrow down results in a chained JSON value | `null`   |
+
+See the [`ChainSource`](./chain_source.md) docs for more detail.
+
+## Examples
+
+```yaml
+# Load chained value from a file
+id: username
+source: !file ./username.txt
+---
+# Prompt the user for a value whenever the request is made
+id: password
+source: !prompt Enter Password
+sensitive: true
+---
+# Use a value from another response
+# Assume the request recipe with ID `login` returns a body like `{"token": "foo"}`
+id: auth_token
+source: !request login
+selector: $.token
+```

docs/src/api/chain_source.md

@@ -0,0 +1,23 @@
+# Chain Source
+
+A chain source defines how a [Chain](./chain.md) gets its value. It populates the `source` field of a chain. There are multiple source types, and the type is specified using [YAML's tag syntax](https://yaml.org/spec/1.2.2/#24-tags).
+
+## Types
+
+| Type      | Value                                | Chained Value                                                   |
+| --------- | ------------------------------------ | --------------------------------------------------------------- |
+| `request` | Request Recipe ID                    | Body of the most recent response for a specific request recipe. |
+| `file`    | Path (relative to current directory) | Contents of the file                                            |
+| `prompt`  | Descriptive prompt for the user      | Value entered by the user                                       |
+
+## Examples
+
+See the [`Chain`](./chain.md) docs for more holistic examples.
+
+```yaml
+!request login
+---
+!file ./username.txt
+---
+!prompt Enter Password
+```

docs/src/api/profile.md

@@ -0,0 +1,21 @@
+# Profile
+
+A profile is a collection of static template values. It's useful for configuring and switching between multiple different environments/settings/etc.
+
+## Fields
+
+| Field  | Type                      | Description                           | Default       |
+| ------ | ------------------------- | ------------------------------------- | ------------- |
+| `id`   | `string`                  | Unique identifier for this profile    | Required      |
+| `name` | `string`                  | Descriptive name to use in the UI     | Value of `id` |
+| `data` | `mapping[string, string]` | Fields, mapped to their static values | `{}`          |
+
+## Examples
+
+```yaml
+id: local
+name: Local
+data:
+  host: http://localhost:5000
+  user_guid: abc123
+```

docs/src/api/request_collection.md

@@ -0,0 +1,78 @@
+# Request Collection
+
+The request collection is the primary configuration for Slumber. It defines which requests can be made, and how to make them. When running a `slumber` instance, a single collection file is loaded. If you want to work with multiple collections at once, you'll have to run multiple instances of Slumber.
+
+## Format & Loading
+
+A collection is defined as a [YAML](https://yaml.org/) file. When you run `slumber`, it will search the current directory for the following default collection files, in order:
+
+- `slumber.yml`
+- `slumber.yaml`
+- `.slumber.yml`
+- `.slumber.yaml`
+
+Whichever of those files is found _first_ will be used. If you want to use a different file for your collection (e.g. if you want to store multiple collections in the same directory), you can override the auto-search with the `--collection` (or `-c`) command line argument. E.g.:
+
+```sh
+slumber -c my-collection.yml
+```
+
+## Fields
+
+A request collection supports the following top-level fields:
+
+| Field      | Type                                         | Description               | Default |
+| ---------- | -------------------------------------------- | ------------------------- | ------- |
+| `profiles` | [`list[Profile]`](./profile.md)              | Static template values    | []      |
+| `requests` | [`list[RequestRecipe]`](./request_recipe.md) | Requests Slumber can send | []      |
+| `chains`   | [`list[Chain]`](./chain.md)                  | Complex template values   | []      |
+
+## Examples
+
+```yaml
+profiles:
+  - id: local
+    name: Local
+    data:
+      host: http://localhost:5000
+      user_guid: abc123
+  - id: prd
+    name: Production
+    data:
+      host: https://httpbin.org
+      user_guid: abc123
+
+chains:
+  - id: username
+    source: !file ./username.txt
+  - id: password
+    source: !prompt Password
+    sensitive: true
+  - id: auth_token
+    source: !request login
+    selector: $.token
+
+# Use YAML anchors for de-duplication
+base: &base
+  headers:
+    Accept: application/json
+    Content-Type: application/json
+
+requests:
+  - <<: *base
+    id: login
+    method: POST
+    url: "{{host}}/anything/login"
+    body: |
+      {
+        "username": "{{chains.username}}",
+        "password": "{{chains.password}}"
+      }
+
+  - <<: *base
+    id: Get User
+    method: GET
+    url: "{{host}}/anything/current-user"
+    query:
+      auth: "{{chains.auth_token}}"
+```

docs/src/api/request_recipe.md

@@ -0,0 +1,34 @@
+# Request Recipe
+
+A request recipe defines how to make a particular request. For a REST API, you'll typically create one request recipe per endpoint.
+
+## Fields
+
+| Field     | Type                                                      | Description                       | Default       |
+| --------- | --------------------------------------------------------- | --------------------------------- | ------------- |
+| `id`      | `string`                                                  | Unique identifier for this recipe | Required      |
+| `name`    | `string`                                                  | Descriptive name to use in the UI | Value of `id` |
+| `method`  | [`TemplateString`](./template_string.md)                  | HTTP request method               | Required      |
+| `url`     | [`TemplateString`](./template_string.md)                  | HTTP request URL                  | Required      |
+| `query`   | [`mapping[string, TemplateString]`](./template_string.md) | HTTP request query parameters     | `{}`          |
+| `headers` | [`mapping[string, TemplateString]`](./template_string.md) | HTTP request headers              | `{}`          |
+| `body`    | [`TemplateString`](./template_string.md)                  | HTTP request body                 | `null`        |
+
+## Examples
+
+```yaml
+id: login
+name: Login
+method: POST
+url: "{{host}}/anything/login"
+headers:
+  accept: application/json
+  content-type: application/json
+query:
+  root_access: yes_please
+body: |
+  {
+    "username": "{{chains.username}}",
+    "password": "{{chains.password}}"
+  }
+```

docs/src/api/template_string.md

@@ -0,0 +1,34 @@
+# Template String
+
+A template string is represented in YAML as a normal string, and thus supports [all of YAML's string syntaxes](https://www.educative.io/answers/how-to-represent-strings-in-yaml). Template strings receive post-processing that injects dynamic values into the string. A templated value is represented with `{{ }}`.
+
+Template strings can generally be used in any _value_ in a request recipe (_not_ in keys). They _cannot_ be used in profiles or chains, to avoid the potential for recursive templating.
+
+## Template Sources
+
+There are several ways of sourcing templating values:
+
+| Source                        | Syntax                | Description                                    |
+| ----------------------------- | --------------------- | ---------------------------------------------- |
+| [Profile](./profile.md) Field | `{{field_name}}`      | Static value from a profile                    |
+| Environment Variable          | `{{env.VARIABLE}}`    | Environment variable from parent shell/process |
+| [Chain](./chain.md)           | `{{chains.chain_id}}` | Complex chained value                          |
+
+## Examples
+
+```yaml
+# Profile value
+"hello, {{location}}"
+---
+# Multiple dynamic values
+"{{greeting}}, {{location}}"
+---
+# Environment variable
+"hello, {{env.LOCATION}}"
+---
+# Chained value
+"hello, {{chains.where_am_i}}"
+---
+# No dynamic values
+"hello, world!"
+```

docs/src/user_guide.md

@@ -0,0 +1 @@
+# User Guide

src/config/mod.rs

@@ -106,6 +106,7 @@ pub struct Chain {
     #[serde(default)]
     pub sensitive: bool,
     /// JSONpath to extract a value from the response. For JSON data only.
+    // TODO strong typing on this
     pub selector: Option<String>,
 }