python/httpie-cli
1
0
Fork 0
mirror of https://github.com/httpie/cli.git synced 2025-08-10 22:42:05 +02:00
Code Activity

Finish docs for v3.0.0 (#1269)

Browse Source 
* WIP

* Rewrite the introduction segment of the Nested JSON

Co-authored-by: Batuhan Taskaya <isidentical@gmail.com>
This commit is contained in:
Jakub Roztocil
2022-01-21 18:24:07 +01:00
committed by GitHub
parent cd877a5e08
commit d2d40eb336
2 changed files with 87 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
CHANGELOG.md
View File

@@ -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))

198
docs/README.md
View File

@@ -598,7 +598,7 @@ Content-Type: application/json
JSON is the *lingua franca* of modern web services, and it is also the **implicit content type** HTTPie uses by default.
Simple example:
```bash
$ http PUT pie.dev/put name=John email=john@example.org
```
@@ -624,7 +624,7 @@ Host: pie.dev
### Explicit JSON
You can use `--json, -j` to explicitly set `Accept` to `application/json` regardless of whether you are sending data (it’s a shortcut for setting the header via the usual header notation: `http url Accept:'application/json, */*;q=0.5'`).
Additionally, HTTPie will try to detect JSON responses even when the `Content-Type` is incorrectly `text/plain` or unknown.
Additionally, HTTPie will try to detect JSON responses even when the `Content-Type` is incorrectly `text/plain` or unknown.
### Non-string JSON fields
@@ -677,132 +677,106 @@ The `:=`/`:=@` syntax is JSON-specific. You can switch your request to `--form`
```json
{
```
"category": "tools",
"search": {
```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.
#### Introduction
Let's start with a simple introduction, and build the JSON object we have seen in the example
above:
```bash
$ http --offline --print=B pie.dev/post \
type=success \
product[name]=something \
product[price]:=10
```
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
},
"id": 1,
"type": "id"
}
}
```
You can also build arrays, through `[]` suffix. Which means create a list, and append the value
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 \
$ 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
{
"search": {
"keywords": [
"soda",
"fries"
]
}
}
```
If you want to specify the direct index, that is also supported:
```bash
$ http --offline --print=B pie.dev/post \
search[keywords][0]=soda \
search[keywords][1]=fries
```
```json
{
"search": {
```json
{
"category": "tools",
"search": {
"keywords": [
"APIs",
"CLI"
}
}
```
],
"type": "keyword"
}
}
```
$ http --offline --print=B pie.dev/post \
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 \
category=tools \
search[type]=keyword \
search[keywords][1]=APIs \
search[keywords][2]=CLI
```
```json
{
"category": "tools",
"search": {
"soda",
null,
null,
"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 \
```bash
$ http --offline --print=B pie.dev/post \
invitation[type]=meetup \
category=tools \
search[type]=platforms \
search[platforms][]=Terminal \
search[platforms][1]=Desktop \
search[platforms][3]=Mobile
```
```json
{
"category": "tools",
"search": {
"platforms": [
"Terminal",
"Desktop",
null,
"Mobile"
],
"type": "platforms"
}
}
```
It is also possible to embed raw JSON to a nested structure, for example:
```bash
$ http --offline --print=B pie.dev/post \
category=tools \
search[type]=platforms \
'search[platforms]:=["Terminal", "Desktop"]' \
search[platforms][]=Web \
search[platforms][]=Mobile
```
```json
{
"category": "tools",
"search": {
"platforms": [
"dates": [
2021,
2022,
2023,
2024,
2025
],
"Terminal",
"Desktop",
"Web",
"Mobile"
],
"type": "platforms"
@@ -811,27 +785,29 @@ It is also possible to embed raw JSON to a nested structure, for example:
```
And just to demonstrate all of these features together, let's create a very deeply nested JSON object:
$ http PUT pie.dev/put \
shallow=value \ # Shallow key-value pair
object[key]=value \ # Nested key-value pair
```bash
$ http PUT pie.dev/put \
shallow=value \ # Shallow key-value pair
object[key]=value \ # Nested key-value pair
array[]:=1 \ # Array — first item
array[1]:=2 \ # Array — second item
array[2]:=3 \ # Array — append (third item)
very[nested][json][3][httpie][power][]=Amaze # Nested object
```
#### Advanced Usage
##### Escaping Behavior
Nested JSON syntax uses the same escaping rules [escaping rules](escaping-rules) as
```
#### Advanced usage
##### Escaping behavior
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 (`\`):
```bash
$ http --offline --print=B pie.dev/post \
'foo\[bar\]:=1' \
'foo\[bar\]:=1' \
'baz[\[]:=2' \
'baz[\]]:=3'
```
@@ -843,11 +819,11 @@ $ http PUT pie.dev/put \
"]": 3
},
"foo[bar]": 1
}
}
```
If you want the send the literal backslash character (`\`), escape it with another backslash:
```bash
$ http --offline --print=B pie.dev/post \
'backslash[\\]:=1'
@@ -907,7 +883,7 @@ $ http --offline --print=B pie.dev/post \
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
an index-based access to an object, HTTPie will error out:
```bash
$ http --offline --print=B pie.dev/post \
'array[]:=1' \
@@ -925,7 +901,7 @@ foo[baz][quux
user[name]:=411 # Defined as an integer
user[name]=string # Overridden with a string
```
```json
{
"user": {
@@ -959,18 +935,12 @@ $ http --offline --print=B pie.dev/post \
```
```http
```bash
$ http --form POST pie.dev/post name='John Smith'
POST /post HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8
name=John+Smith
```
name=John+Smith
```
### File upload forms
If one or more file fields is present, the serialization and content type is `multipart/form-data`:
@@ -1253,7 +1223,7 @@ the [sessions](#sessions) feature.
```
### Password prompt
```bash
$ http -a username pie.dev/basic-auth/username/password
```
@@ -1592,7 +1562,7 @@ The response headers are downloaded always, even if they are not part of the out
Or the output of another program:
```bash
```bash
$ grep '401 Unauthorized' /var/log/httpd/error_log | http POST pie.dev/post
```