extern/httpie-cli
1
0
Fork 1
mirror of https://github.com/httpie/cli.git synced 2024-11-07 16:34:35 +01:00
Code Issues Packages Projects Releases Wiki Activity

Improved examples.

Browse Source
This commit is contained in:
Jakub Roztocil 2012-08-09 23:36:29 +02:00
parent c01dd8d64a
commit 27f08920c4
1 changed files with 62 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
README.rst
View File

@ -114,53 +114,54 @@ Examples
--------
Send a ``HEAD`` request:
Custom `HTTP method`_, `HTTP headers`_ and `JSON`_ data:
.. code-block:: bash
$ http HEAD example.org
$ http PUT example.org X-API-Token:123 name=John
Submit a form:
Submitting `forms`_:
.. code-block:: bash
$ http --form POST example.org hello=World
$ http -f POST example.org hello=World
Send a ``PUT`` request with a custom header and some JSON data:
See the request that is being sent using on of the `output options`_:
.. code-block:: bash
$ http PUT example.org X-API-Token:123 name='David Bowie'
See the request that is being sent:
.. code-block:: bash
$ http --verbose example.org
$ http -v example.org
Use `Github API`_ to post a comment on an issue:
Use `Github API`_ to post a comment on an issue with `authentication`_:
.. code-block:: bash
$ http -a USERNAME POST https://api.github.com/repos/jkbr/httpie/issues/83/comments body='HTTPie is awesome!'
Upload a file:
Upload a file using `redirected input`_:
.. code-block:: bash
$ http example.org < file.json
Download a file:
Download a file and save it via `redirected output`_:
.. code-block:: bash
$ http example.org/file > file
--------
*What follows is a detailed documentation. It covers the command syntax,
advances usage, and also features additional examples.*
============
HTTP Method
============
@ -172,7 +173,7 @@ The name of the HTTP method comes right before the URL argument:
$ http DELETE example.org/todos/7
It makes the command look similar to the actual ``Request-Line`` that is sent:
Which looks similar to the actual ``Request-Line`` that is sent:
.. code-block:: http
@ -250,7 +251,7 @@ You can use ``\`` to escape characters that shouldn't be used as separators
(or parts thereof). e.g., ``foo\==bar`` will become a data key/value
pair (``foo=`` and ``bar``) instead of a URL parameter.
No that data fields aren't the only way to specify request data,
Note that data fields aren't the only way to specify request data,
`redirected input`_ allows passing arbitrary data to be sent with the request.
@ -271,7 +272,7 @@ both of which can be overwritten:
================ =======================================
You can use ``--json`` / ``-j`` to set ``Accept`` to ``application/json``
regardless of whether you are sending data (it's a shortcut for using setting
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``).
@ -323,6 +324,12 @@ into the resulting object:
}
Send JSON data stored in a file (see `redirected input`_ for more examples):
.. code-block:: bash
$ http POST api.example.com/person/1 < person.json
=====
Forms
@ -330,9 +337,10 @@ Forms
Submitting forms is very similar to sending `JSON`_ requests. Often the only
difference is in adding the ``--form`` / ``-f`` option, which ensures that
data fields are serialized and ``Content-Type`` is set to
data fields are serialized as, and ``Content-Type`` is set to,
``application/x-www-form-urlencoded; charset=utf-8``.
-------------
Regular Forms
-------------
@ -355,7 +363,7 @@ Regular Forms
File Upload Forms
-----------------
When one or more file fields are present, the content type is
If one or more file fields is present, the serialization and content type is
``multipart/form-data``:
.. code-block:: bash
@ -397,8 +405,7 @@ To set custom headers you can use the ``Header:Value`` notation:
X-Foo: Bar
There are a couple of default headers that HTTPie sets, but they can easily
be overwritten:
There are a couple of default headers that HTTPie sets:
.. code-block:: http
@ -409,6 +416,9 @@ be overwritten:
Host: <taken-from-URL>
Any of the default headers can be overwritten.
==============
Authentication
==============
@ -488,9 +498,10 @@ In your ``~/.bash_profile``:
HTTPS
=====
To skip the host's SSL certificate verification, you can pass ``--verify=no``.
You can also specify a custom CA bundle path using the same option. The same
can also be done via the environment variable ``REQUESTS_CA_BUNDLE``.
To skip the host's SSL certificate verification, you can pass ``--verify=no``
(default is ``yes``). You can also use ``--verify`` to set a custom CA bundle
path. The path can also be configured via the environment variable
``REQUESTS_CA_BUNDLE``.
==============
@ -552,7 +563,7 @@ Character Stands for
``b`` Response body.
========== ==================
Print both the request and response headers:
Print request and response headers:
.. code-block:: bash
@ -569,14 +580,14 @@ request, except that it applies to any HTTP method you use.
Let's say that there is an API that returns the whole resource when it is
updated, but you are only interested in the response headers to see the
status code after the update:
status code after an update:
.. code-block:: bash
$ http --headers PATCH example.org/Really-Huge-Resource name='New Name'
Since we are only printing the HTTP headers here, the connection to server
Since we are only printing the HTTP headers here, the connection to the server
is closed as soon as all the response headers have been received.
Therefore, bandwidth and time isn't wasted downloading the body
which you don't care about.
@ -657,7 +668,7 @@ Body Data From a Filename
``@/path/to/file``) whose content is used as if it came from ``stdin``.
It has the advantage that **the** ``Content-Type``
**header will automatically be set** to the appropriate value based on the
**header is automatically set** to the appropriate value based on the
filename extension. For example, the following request sends the
verbatim contents of that XML file with ``Content-Type: application/xml``:
@ -670,7 +681,8 @@ verbatim contents of that XML file with ``Content-Type: application/xml``:
Terminal Output
=================
HTTPie does several things by default to make its terminal output easy to read.
HTTPie does several things by default in order to make its terminal output
easy to read.
---------------------
@ -679,7 +691,7 @@ Colors and Formatting
Syntax highlighting is applied to HTTP headers and bodies (where it makes
sense). You can choose your prefered color scheme via the ``--style`` option
if you don't like the default onw (see ``$ http --help`` for the possible
if you don't like the default one (see ``$ http --help`` for the possible
values).
Also, the following formatting is applied:
@ -702,16 +714,16 @@ Binary data
-----------
Binary data is suppressed for terminal output, which makes it safe to perform
requests to URLs send back binary data. Binary data is suppressed also in
requests to URLs that send back binary data. Binary data is suppressed also in
redirected, but prettified output. The connection is closed as soon as we know
that the response body is binary,
.. code-block:: bash
http example.org/File.mov
http example.org/Movie.mov
You will immediately see something like this:
You will nearly instantly see something like this:
.. code-block:: http
@ -734,7 +746,7 @@ HTTPie uses **different defaults** for redirected output than for
`terminal output`_:
* Formatting and colors aren't applied (unless ``--pretty``, ``--format``,
or ``--colors``, is set).
or ``--colors`` is set).
* Only the response body is printed (unless one of the `output options`_ is set).
* Also, binary data isn't suppressed.
@ -756,7 +768,7 @@ Download an image of Octocat, resize it using ImageMagick, upload it elsewhere:
$ http octodex.github.com/images/original.jpg | convert - -resize 25% - | http example.org/Octocats
Force colorizing and formatting, and show both the request and response in
Force colorizing and formatting, and show both the request and the response in
``less`` pager:
.. code-block:: bash
@ -764,13 +776,17 @@ Force colorizing and formatting, and show both the request and response in
$ http --pretty --verbose example.org | less -R
The ``-R`` flag tells ``less`` to interpret color escape sequences included
HTTPie`s output.
==================
Streamed Responses
==================
Responses are downloaded and printed in chunks, which allows for streaming
and large file downloads without using too much RAM. However, when
`colors and formatting`_ are applied, the whole response is buffered and only
`colors and formatting`_ is applied, the whole response is buffered and only
then processed at once.
@ -781,7 +797,7 @@ You can use the ``--stream, -S`` flag to make two things happen:
2. Streaming becomes enabled even when the output is prettified: It will be
applied to **each line** of the response and flushed immediately. This makes
it possible to have a nice output of long-lived requests, such as one
it possible to have a nice output for long-lived requests, such as one
to the Twitter streaming API.
@ -792,7 +808,7 @@ Prettified streamed response:
$ http --stream -f -a YOUR-TWITTER-NAME https://stream.twitter.com/1/statuses/filter.json track='Justin Bieber'
Streamed output by small chunks:
Streamed output by small chunks alá ``tail -f``:
.. code-block:: bash
@ -870,6 +886,11 @@ The two modes, ``--pretty`` (default for terminal) and ``--ugly, -u``
(default for redirected output), allow for both user-friendly interactive use
and usage from scripts, where HTTPie serves as a generic HTTP client.
As HTTPie is still under heavy development, the existing command line
syntax and some of the ``--OPTIONS`` may change slightly before
HTTPie reaches its final version ``1.0``. All changes are recorded in the
`changelog`_.
==========
Contribute
@ -935,6 +956,8 @@ Please see `LICENSE`_.
Changelog
=========
*You can click a version name to see a diff with the previous one.*
* `0.2.8dev`_
* Added exit status code ``2`` for timed-out requests.
* Added ``--colors`` and ``--format`` in addition to ``--pretty``, to