From d2d40eb3360f0fe1d871466aa4aadd85c618da12 Mon Sep 17 00:00:00 2001 From: Jakub Roztocil Date: Fri, 21 Jan 2022 18:24:07 +0100 Subject: [PATCH] Finish docs for v3.0.0 (#1269) * WIP * Rewrite the introduction segment of the Nested JSON Co-authored-by: Batuhan Taskaya --- CHANGELOG.md | 6 +- docs/README.md | 198 +++++++++++++++++++++---------------------------- 2 files changed, 87 insertions(+), 117 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d69956cb..435b5723 100644 --- 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 index 0c1cd946..063ebd4b 100644 --- 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. - -```json -{ - "product": { - "name": "something", - "price": 10 - }, - "type": "success" -} -``` - -You can also build arrays, through `[]` suffix. Which means create a list, and append the value -to that list: - -```bash -$ http --offline --print=B pie.dev/post \ - search[keywords][]=soda \ - search[keywords][]=fries -``` +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 { + "category": "tools", "search": { - "keywords": [ - "soda", - "fries" - ] + "id": 1, + "type": "id" } } ``` -If you want to specify the direct index, that is also supported: +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][0]=soda \ - search[keywords][1]=fries + category=tools \ + search[type]=keyword \ + search[keywords][]=APIs \ + search[keywords][]=CLI ``` ```json { + "category": "tools", "search": { "keywords": [ - "soda", - "fries" - ] + "APIs", + "CLI" + ], + "type": "keyword" } } ``` -You can also create 'sparse arrays' (arrays where you set 2 non-consecutive indexes), which -the missing values gets nullified: +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][2]=soda \ - search[keywords][5]=fries \ - search[keywords][]=fish + category=tools \ + search[type]=keyword \ + search[keywords][1]=APIs \ + search[keywords][2]=CLI ``` ```json { + "category": "tools", "search": { "keywords": [ + "CLIs", + "API" + ], + "type": "keyword" + } +} +``` + +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 \ + category=tools \ + search[type]=platforms \ + search[platforms][]=Terminal \ + search[platforms][1]=Desktop \ + search[platforms][3]=Mobile +``` + +```json +{ + "category": "tools", + "search": { + "platforms": [ + "Terminal", + "Desktop", null, - null, - "soda", - 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