view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

Current valid config keys are:

- verbose

    Boolean, when enabled, dumps request/response to STDOUT (defaults to "0")

- deserialize\_response 

    Boolean, when enabled response body is parsed based on the `Content-Type`
    header (defaults to "1")

- pretty\_printer

    Must be one of the supported modules (i.e. Data::Dumper or JSON).
    Use tab completion to see currently supported values (defaults to "JSON").

- binmode

    Used to set encoding of STDIN and STDOUT handles (defaults to "utf8")

**TODO:** provide a means for aliasing endpoints so that configuration
is shared across multiple endpoints.

## History and Scripting

Just like configuration, command history is maintained separately for each
endpoint specified on the command-line and is persisted across sessions
(assuming you have a capable Term::Readline library installed).  You can
interrogate the history using the (surprisingly named) `history` command.
It supports a small subset of the `bash` history command:

        # dump all history
        http://my-server.com> history

        # dump last 5 entries
        http://my-server.com> history 5

        # delete specific history entries
        http://my-server.com> history -d 4

        # clear history
        http://my-server.com> history -c

Presto also provides a way of saving and replaying bits of your command
history. Here are some examples:

        # save all history to script file "my-script"
        http://my-server.com> save my-script

        # save the last 5 history entries
        http://my-server.com> save my-script 5

        # save entries 3-7
        http://my-server.com> save my-script 3..7 

To replay scripts:

        http://my-server.com> source my-script

        # prompt before each command
        http://my-server.com> source -i my-script

## Variable interpolation

At times (especially when working with scripts) it might be handy to
use elements from a previous response to affect a subsequent request.
Anything inside a balanced `$(...)` will be interpolated for you.
For instance, a very contrived example:

        # hypothetical authentication protocal that returns a token in the response headers
        http://my-server.com> POST /auth.json username=jdoe&password=s3cr3t
        {"authenticated":true}

        # see the authentication token
        http://my-server.com> echo $(HEADER[X-Auth-Token])
        2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae

If you need to include that in subsequent request, you can use the "stash" feature:

        # store the value
        http://my-server.com> stash auth-token $(HEADER[X-Auth-Token])

        # use the value later
        http://my-server.com> header X-Auth-Token $(STASH[auth-token])

Those variable substitutions can be used anywhere in a command.  `HEADER`
and `BODY` always refer to the most recent request while the `STASH`
is a persisted for the life of the process.

One useful feature for scripting is to prompt for user input.  You can do
this by using the `PROMPT` pseudo-variable.  The first set of brackets
specify the prompt value.  The second (optional) set of brackets specify
the initial value.  An example:

        # collect the username/password from the user
        http://my-server.com> stash username $(PROMPT[username:])
        http://my-server.com> stash password $(PROMPT[password:])

        # use the stashed values
        http://my-server.com> authorization $(STASH[username]) $(STASH[password])
        http://my-server.com> GET /$(STASH[username])/profile

        # or use a value that was prompted for directly (without stashing it)
        http://my-server.com> GET /products 'created_on=$(PROMPT[Created on (YYYY-MM-DD):])'

        # you can also specify initial values
        http://my-server.com> GET /products 'status=$(PROMPT[Product status:][active])'

You may also specify a local file to use as an argument to a command.  An example:

        http://my-server.com> POST /products $(FILE[my-product.xml])

The file is assumed to be in the same encoding as the `binmode`
configuration.  If it is using a different character set, you can specify
that in a second bracketed parameter:

        http://my-server.com> POST /products $(FILE[my-product.xml][latin-1])

The contents of the file will be slurped, decoded and included as an
argument to the command as if you had typed it on the command-line
directly.

**TODO:** Allow data structure references (from `STASH` or even `BODY`)
to be passed to a POST or PUT command which is then serialized based
on the content-type of the request before being sent over the wire.

## (EXPERIMENTAL) Data::DPath integration

As an add-on to the variable interpolated described above, you can
use dpath expressions to further process the data returned from the
REST service.  Another very contrived example:

        http://my-server.com> GET /products.json
        [{"id":"1","name":"My Product"},{"id":"2","name":"Another Product"}]

        # issue a request to /product/2.json
        http://my-server.com> GET /product/$(BODY/id[-1]).json
        {"id":2,"name":"Another Product"}

In this example, anything after `BODY` (including the `/`) is passed
to [Data::DPath](https://metacpan.org/pod/Data::DPath) and the result is then injected in it's place (the target
data for `BODY` being the previous request's response data).

This feature will work on `$(STASH)` values as well.

# CAVEAT EMPTOR

This is beta-quality code and while I use it in my own daily workflow,
it is likely riddled with horribly obvious bugs and missing functionality
(let alone undocumented features).

# ACKNOWLEDGEMENTS

Much of this was inspired by [resty](https://github.com/micha/resty)
which is a rather magical (aka convoluted) set of bash functions (at least
for this occassional bash programmer).  After attempting to understand
and enhance [resty](https://github.com/micha/resty), I decided to try
my hand at creating something a little more perlish.

A big thank you to [Shutterstock Images](http://shutterstock.com) for
allowing me to work on this on company time and release it to the CPAN.

# AUTHORS