Finish docs for v3.0.0 (#1269)

jkbrzt · isidentical · web-flow · commit d2d40eb3360f · 2022-01-21T20:24:07.000+03:00
* WIP

* Rewrite the introduction segment of the Nested JSON

Co-authored-by: Batuhan Taskaya &lt;isidentical@gmail.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,7 +5,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [3.0.0.dev0](https://github.com/httpie/httpie/compare/2.6.0...master) (unreleased)
 
-- Drop support for Python 3.6. ([#1177](https://github.com/httpie/httpie/issues/1177))
+- Dropped support for Python 3.6. ([#1177](https://github.com/httpie/httpie/issues/1177))
 - Improved startup time by 40%. ([#1211](https://github.com/httpie/httpie/pull/1211))
 - Added support for nested JSON syntax. ([#1169](https://github.com/httpie/httpie/issues/1169))
 - Added `httpie plugins` interface for plugin management. ([#566](https://github.com/httpie/httpie/issues/566))
@@ -15,12 +15,12 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 - Added support for _receiving_ multiple HTTP headers lines with the same name. ([#1207](https://github.com/httpie/httpie/issues/1207))
 - Added support for basic JSON types on `--form`/`--multipart` when using JSON only operators (`:=`/`:=@`). ([#1212](https://github.com/httpie/httpie/issues/1212))
 - Added support for automatically enabling `--stream` when `Content-Type` is `text/event-stream`. ([#376](https://github.com/httpie/httpie/issues/376))
-- Added support for displaying the total elapsed time throguh `--meta`/`-vv` or `--print=m`. ([#243](https://github.com/httpie/httpie/issues/243))
+- Added support for displaying the total elapsed time through `--meta`/`-vv` or `--print=m`. ([#243](https://github.com/httpie/httpie/issues/243))
 - Added new `pie-dark`/`pie-light` (and `pie`) styles that match with [HTTPie for Web and Desktop](https://httpie.io/product). ([#1237](https://github.com/httpie/httpie/issues/1237))
 - Added support for better error handling on DNS failures. ([#1248](https://github.com/httpie/httpie/issues/1248))
 - Added support for storing prompted passwords in the local sessions. ([#1098](https://github.com/httpie/httpie/issues/1098))
 - Added warnings about the `--ignore-stdin`, when there is no incoming data from stdin. ([#1255](https://github.com/httpie/httpie/issues/1255))
-- Broken plugins will no longer crash the whole application. ([#1204](https://github.com/httpie/httpie/issues/1204))
+- Fixed crashing due to broken plugins. ([#1204](https://github.com/httpie/httpie/issues/1204))
 - Fixed auto addition of XML declaration to every formatted XML response. ([#1156](https://github.com/httpie/httpie/issues/1156))
 - Fixed highlighting when `Content-Type` specifies `charset`. ([#1242](https://github.com/httpie/httpie/issues/1242))
 - Fixed an unexpected crash when `--raw` is used with `--chunked`. ([#1253](https://github.com/httpie/httpie/issues/1253))
diff --git a/docs/README.md b/docs/README.md
@@ -598,7 +598,7 @@ Content-Type: application/json
 
 ## JSON
 
-JSON is the *lingua franca* of modern web services and it is also the **implicit content type** HTTPie uses by default.
+JSON is the *lingua franca* of modern web services, and it is also the **implicit content type** HTTPie uses by default.
 
 Simple example:
 
@@ -624,7 +624,7 @@ Host: pie.dev
 If your command includes some data [request items](#request-items), they are serialized as a JSON object by default. HTTPie also automatically sets the following headers, both of which can be overwritten:
 
 |         Header | Value                         |
-| -------------: | ----------------------------- |
+|---------------:|-------------------------------|
 | `Content-Type` | `application/json`            |
 |       `Accept` | `application/json, */*;q=0.5` |
 
@@ -677,132 +677,106 @@ The `:=`/`:=@` syntax is JSON-specific. You can switch your request to `--form`
 and string, float, and number values will continue to be serialized (as string form values).
 Other JSON types, however, are not allowed with `--form` or `--multipart`.
 
-### Nested JSON fields
+### Nested JSON
 
-In the past (pre-3.0), HTTPie's data operators (`=`/`:=`) allowed you to
-directly create basic JSON objects right from your terminal. Though this
-functionality was limited to only top-level keys.
-
-```bash
-$ http --offline --print=B pie.dev/post \
-  type=success
-```
-
-```json
-{
-    "type": "success"
-}
-```
-
-For embedding more complex JSON objects, you needed to use the `:=` operator.
-
-```bash
-$ http --offline --print=B pie.dev/post \
-  type=success \
-  'product:={"name":"something", "price":10}'
-```
-
-```json
-{
-    "product": {
-        "name": "something",
-        "price": 10
-    },
-    "type": "success"
-}
-```
-
-Starting with 3.0, we have created a mini language in HTTPie's own syntax to
-build complex JSON objects with ease. This syntax was inspired by the [JSON form](https://www.w3.org/TR/html-json-forms/)
-proposal for HTML, though we have changed a lot of parts to offer the best experience.
+If your use case involves sending complex JSON objects as part of the request body,
+HTTPie can help you build them right from your terminal. You still use the existing
+data field operators (`=`/`:=`) but instead of specifying a top-level field name (like `key=value`), you specify a path declaration. This tells HTTPie where and how to put the given value inside of an object.
 
 #### Introduction
 
-Let's start with a simple introduction, and build the JSON object we have seen in the example
-above:
+Let's start with a simple example, and build a simple search query:
 
 ```bash
 $ http --offline --print=B pie.dev/post \
-  type=success \
-  product[name]=something \
-  product[price]:=10
+  category=tools \
+  search[type]=id \
+  search[id]:=1
 ```
 
-With the new syntax, you can designate the path for the value. For example `product[name]` means
-create a new object under the `product` key, and set the `name` field of that object to the given
-value.
+In the example above, the `search[type]` is an instruction for creating an object called `search`, and setting the `type` field of it to the given value (`"id"`).
+
+Also note that, just as the regular syntax, you can use the `:=` operator to directly pass raw JSON values (e.g numbers in the case above).
 
 ```json
 {
-    "product": {
-        "name": "something",
-        "price": 10
-    },
-    "type": "success"
+    "category": "tools",
+    "search": {
+        "id": 1,
+        "type": "id"
+    }
 }
 ```
 
-You can also build arrays, through `[]` suffix. Which means create a list, and append the value
-to that list:
+Building arrays is also possible, through `[]` suffix (an append operation). This tells HTTPie to create an array in the given path (if there is not one already), and append the given value to that array.
 
 ```bash
 $ http --offline --print=B pie.dev/post \
-  search[keywords][]=soda \
-  search[keywords][]=fries
+  category=tools \
+  search[type]=keyword \
+  search[keywords][]=APIs \
+  search[keywords][]=CLI
 ```
 
 ```json
 {
+    "category": "tools",
     "search": {
         "keywords": [
-            "soda",
-            "fries"
-        ]
+            "APIs",
+            "CLI"
+        ],
+        "type": "keyword"
     }
 }
 ```
 
-If you want to specify the direct index, that is also supported:
+If you want to explicitly specify the position of elements inside an array,
+you can simply pass the desired index as the path:
 
 ```bash
 $ http --offline --print=B pie.dev/post \
-  search[keywords][0]=soda \
-  search[keywords][1]=fries
+  category=tools \
+  search[type]=keyword \
+  search[keywords][1]=APIs \
+  search[keywords][2]=CLI
 ```
 
 ```json
 {
+    "category": "tools",
     "search": {
         "keywords": [
-            "soda",
-            "fries"
-        ]
+            "CLIs",
+            "API"
+        ],
+        "type": "keyword"
     }
 }
 ```
 
-You can also create 'sparse arrays' (arrays where you set 2 non-consecutive indexes), which
-the missing values gets nullified:
+If there are any missing indexes, HTTPie will nullify them in order to create a concrete object that can be sent:
 
 ```bash
 $ http --offline --print=B pie.dev/post \
-  search[keywords][2]=soda \
-  search[keywords][5]=fries \
-  search[keywords][]=fish
+  category=tools \
+  search[type]=platforms \
+  search[platforms][]=Terminal \
+  search[platforms][1]=Desktop \
+  search[platforms][3]=Mobile
 ```
 
 ```json
 {
+    "category": "tools",
     "search": {
-        "keywords": [
-            null,
-            null,
-            "soda",
+        "platforms": [
+            "Terminal",
+            "Desktop",
             null,
-            null,
-            "fries",
-            "fish"
-        ]
+            "Mobile"
+        ],
+        "type": "platforms"
     }
 }
 ```
@@ -811,27 +785,29 @@ It is also possible to embed raw JSON to a nested structure, for example:
 
 ```bash
 $ http --offline --print=B pie.dev/post \
-  invitation[type]=meetup \
-  'invitation[dates]:=[2021, 2022, 2023, 2024]' \
-  invitation[dates][]:=2025
+  category=tools \
+  search[type]=platforms \
+  'search[platforms]:=["Terminal", "Desktop"]' \
+  search[platforms][]=Web \
+  search[platforms][]=Mobile
 ```
 
 ```json
 {
-    "invitation": {
-        "dates": [
-            2021,
-            2022,
-            2023,
-            2024,
-            2025
+    "category": "tools",
+    "search": {
+        "platforms": [
+            "Terminal",
+            "Desktop",
+            "Web",
+            "Mobile"
         ],
-        "type": "meetup"
+        "type": "platforms"
     }
 }
 ```
 
-And for the last, let's create a very deeply nested JSON object:
+And just to demonstrate all of these features together, let's create a very deeply nested JSON object:
 
 ```bash
 $ http PUT pie.dev/put \
@@ -843,11 +819,11 @@ $ http PUT pie.dev/put \
     very[nested][json][3][httpie][power][]=Amaze   # Nested object
 ```
 
-#### Advanced Usage
+#### Advanced usage
 
-##### Escaping Behavior
+##### Escaping behavior
 
-Nested JSON syntax uses the same escaping rules [escaping rules](escaping-rules) as
+Nested JSON syntax uses the same [escaping rules](#escaping-rules) as
 the terminal. There are 3 special characters, and 1 special token that you can escape.
 
 If you want to send a bracket as is, escape it with a backslash (`\`):
@@ -907,7 +883,7 @@ $ http --offline --print=B pie.dev/post \
 }
 ```
 
-##### Guiding Syntax Errors
+##### Guiding syntax errors
 
 If you make a typo or forget to close a bracket, the errors will guide you to fix it. For example:
 
@@ -925,7 +901,7 @@ foo[baz][quux
 
 You can follow to given instruction (adding a `]`) and repair your expression.
 
-##### Type Safety
+##### Type safety
 
 Each container path (e.g `x[y][z]` in `x[y][z][1]`) has a certain type, which gets defined with
 the first usage and can't be changed after that. If you try to do a key-based access to an array or
@@ -959,18 +935,12 @@ $ http --offline --print=B pie.dev/post \
 
 ### Raw JSON
 
-Please note that on some very complex JSON structures, manually building the JSON object right from the terminal
-might be more complicated compared to typing it on a file and directly sending it through HTTPie. Depending on your
-use case, some of the following examples can help:
+For very complex JSON structures, it may be more convenient to [pass it as raw request body](#raw-request-body), for example:
 
 ```bash
 $ echo -n '{"hello": "world"}' | http POST pie.dev/post
 ```
 
-```bash
-$ http --raw '{"hello": "world"}' POST pie.dev/post
-```
-
 ```bash
 $ http POST pie.dev/post < files/data.json
 ```
@@ -1253,7 +1223,7 @@ the [sessions](#sessions) feature.
 The currently supported authentication schemes are Basic and Digest (see [auth plugins](#auth-plugins) for more). There are two flags that control authentication:
 
 |              Flag | Arguments                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| ----------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|------------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 |      `--auth, -a` | Pass either a `username:password` pair or a `token` as the argument. If the selected authenticated method requires username/password combination and if you only specify a username (`-a username`), you’ll be prompted for the password before the request is sent. To send an empty password, pass `username:`. The `username:password@hostname` URL syntax is supported as well (but credentials passed via `-a` have higher priority) |
 | `--auth-type, -A` | Specify the auth mechanism. Possible values are `basic`, `digest`, `bearer` or the name of any [auth plugins](#auth-plugins) you have installed. The default value is `basic` so it can often be omitted                                                                                                                                                                                                                                  |
 
@@ -1592,7 +1562,7 @@ The response headers are downloaded always, even if they are not part of the out
 In addition to crafting structured [JSON](#json) and [forms](#forms) requests with the [request items](#request-items) syntax, you can provide a raw request body that will be sent without further processing.
 These two approaches for specifying request data (i.e., structured and raw) cannot be combined.
 
-There’re three methods for passing raw request data: piping via `stdin`,
+There are three methods for passing raw request data: piping via `stdin`,
 `--raw='data'`, and `@/file/path`.
 
 ### Redirected Input
