view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

        # 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

- Brian Phillips <bphillips@cpan.org>
- Matt Perry <matt@mattperry.com> (current maintainer)

# COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Brian Phillips and Shutterstock Images (http://shutterstock.com).

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.