7. Using the rest-shell

The rest-shell is a command-line shell that aims to make writing REST-based applications easier. It is based on spring-shell and integrated with Spring HATEOAS in such a way that REST resources that output JSON compliant with Spring HATEOAS can be discovered by the shell and interactions with the REST resources become much easier than by manipulating the URLs in bash using a tool like curl.

The rest-shell provides a number of useful commands for discovering and interacting with REST resources. For example discover will discover what resources are available and print out an easily-readable table of rels and URIs that relate to those resources. Once these resources have been discovered, the rel of those URIs can be used in place of the URI itself in most operations, thus cutting down on the amount of typing needed to issue HTTP requests to your REST resources.

7.1 Installing the rest-shell

If you're using Mac OS X and Homebrew, then installation is super easy:

brew install rest-shell

Other platforms are simple as well: just download the archive from the GitHub page and unzip it to a location on your local hard drive.

7.2 Discovering resources

The rest-shell is aimed at making it easier to interact with REST resources by managing the session baseUri much like a directory in a filesystem. Whenever resources are discovered, you can then follow to a new baseUri, which means you can then use relative URIs. Here's an example of discovering resources, then following a link by referencing its rel value, and then using a relative URI to access resources under that new baseUri:

http://localhost:8080:> discover
rel                href
========================================================
address            http://localhost:8080/address
family             http://localhost:8080/family
people             http://localhost:8080/person
profile            http://localhost:8080/profile

http://localhost:8080:> follow people
http://localhost:8080/person:> list
rel             href
===================================================
people.Person    http://localhost:8080/person/1
people.Person    http://localhost:8080/person/2
people.search    http://localhost:8080/person/search

http://localhost:8080/person:> get 1
> GET http://localhost:8080/person/1

< 200 OK
< ETag: "2"
< Content-Type: application/json
<
{
    "links" : [ {
        "rel" : "self",
        "href" : "http://localhost:8080/person/1"
    }, {
        "rel" : "peeps.Person.profiles",
        "href" : "http://localhost:8080/person/1/profiles"
    }, {
        "rel" : "peeps.Person.addresses",
        "href" : "http://localhost:8080/person/1/addresses"
    } ],
    "name" : "John Doe"
}

NOTE: If you want tab completion of discovered rels, just use the --rel flag.

7.3 Creating new resources

The rest-shell can do basic parsing of JSON data within the shell (though there are some limitations due to the nature of the command line parsing being sensitive to whitespace). This makes it easy to create new resources by including JSON data directly in the shell:

http://localhost:8080/person:> post --data "{name: 'John Doe'}"
> POST http://localhost:8080/person/

< 201 CREATED
< Location: http://localhost:8080/person/8
< Content-Length: 0
<

http://localhost:8080/person:> get 8
> GET http://localhost:8080/person/8

< 200 OK
< ETag: "0"
< Content-Type: application/json
<
{
    "links" : [ {
        "rel" : "self",
        "href" : "http://localhost:8080/person/8"
    }, {
        "rel" : "people.Person.addresses",
        "href" : "http://localhost:8080/person/8/addresses"
    }, {
        "rel" : "people.Person.profiles",
        "href" : "http://localhost:8080/person/8/profiles"
    } ],
    "name" : "John Doe"
}

If your needs of representing JSON get more complicated than what the spring-shell interface can handle, you can create a directory somewhere with .json files in it, one file per entitiy, and use the --from option to the post command. This will walk the directory and make a POST request for each .json file found.

http://localhost:8080/person:> post --from work/people_to_load
128 items uploaded to the server using POST.
http://localhost:8080/person:>

You can also reference a specific file rather than an entire directory.

http://localhost:8080/person:> post --from work/people_to_load/someone.json
1 items uploaded to the server using POST.
http://localhost:8080/person:>

7.4 Passing query parameters

If you're calling URLs that require query parameters, you'll need to pass those as a JSON-like fragment in the --params parameter to the get and list commands. Here's an example of calling a URL that expects parameter input:

http://localhost:8080/person:> get search/byName --params "{name: 'John Doe'}"
    

7.5 Outputing results to a file

It's not always desirable to output the results of an HTTP request to the screen. It's handy for debugging but sometimes you want to save the results of a request because they're not easily reproducible or any number of other equally valid reasons. All the HTTP commands take an --output parameter that writes the results of an HTTP operation to the given file. For example, to output the above search to a file:

http://localhost:8080/person:> get search/byName --params "{name: 'John Doe'}" --output by_name.txt >> by_name.txt
http://localhost:8080/person:>

7.6 Sending complex JSON

Because the rest-shell uses the spring-shell underneath, there are limitations on the format of the JSON data you can enter directly into the command line. If your JSON is too complex for the simplistic limitations of the shell --data parameter, you can simply load the JSON from a file or from all the files in a directory.

When doing a post or put, you can optionally pass the --from parameter. The value of this parameter should either be a file or a directory. If the value is a directory, the shell will read each file that ends with .json and make a POST or PUT with the contents of that file. If the parameter is a file, then the rest-shell will simpy load that file and POST/PUT that data in that individual file.

7.7 Shelling out to bash

One of the nice things about spring-shell is that you can directly shell out commands to the underlying terminal shell. This is useful for doing things like load a JSON file in an editor. For instance, assume I have the Sublime Text 2 command subl in my path. I can then load a JSON file for editing from the rest-shell like this:

http://localhost:8080/person:> ! subl test.json
        http://localhost:8080/person:>

I then edit the file as I wish. When I'm ready to POST that data to the server, I can do so using the --from parameter:

http://localhost:8080/person:> post --from test.json
1 items uploaded to the server using POST.
http://localhost:8080/person:>

7.8 Setting context variables

Starting with rest-shell version 1.1, you can also work with context variables during your shell session. This is useful for saving settings you might reference often. The rest-shell now integrates Spring Expression Language support, so these context variables are usable in expressions within the shell.

http://localhost:8080/person:> var set --name specialUri --value http://longdomainname.com/api
http://localhost:8080/person:> var get --name specialUri
http://longdomainname.com/api
http://localhost:8080/person:> var list
{
  "responseHeaders" : {
    ... HTTP headers from last request
  },
  "responseBody" : {
    ... Body from the last request
  },
  "specialUri" : "http://longdomainname.com/api",
  "requestUrl" : ... URL from the last request,
  "env" : {
    ... System properties and environment variables
  }
}

The variables are accessible from SpEL expressions which are valid in a number of different contexts, most importantly in the path argument to the HTTP and discover commands, and in the data argument to the put and post commands.

Since the rest-shell is aware of environment variables and system properties, you can incorporate external parameters into your interaction with the shell. For example, to externally define a baseUri, you could set a system property before invoking the shell. The shell will incorporate anything defined in the JAVA_OPTS environment variable, so you could parameterize your interaction with a REST service.

JAVA_OPTS="-DbaseUri=http://mylongdomain.com/api" rest-shell

http://localhost:8080:> discover #{env.baseUri}
rel                href
=================================================================
... resources for this URL
http://mylongdomain.com/api:>

7.9 Per-user shell initialization

The rest-shell supports a "dotrc" type of initialization by reading in all files found in the $HOME/.rest-shell/ directory and assuming they have shell commands in them. The rest-shell will execute these commands on startup. This makes it easy to set variables for commonly-used URIs or possibly set a baseUri.

echo "var set --name svcuri --value http://api.myservice.com/v1" > ~/.rest-shell/00-vars
echo "discover #{svcuri}" > ~/.rest-shell/01-baseUri

> rest-shell

INFO: No resources found...
INFO: Base URI set to 'http://api.myservice.com/v1'

 ___ ___  __ _____  __  _  _     _ _  __
| _ \ __/' _/_   _/' _/| || |   / / | \ \
| v / _|`._`. | | `._`.| >< |  / / /   > >
|_|_\___|___/ |_| |___/|_||_| |_/_/   /_/
1.2.1.RELEASE

Welcome to the REST shell. For assistance hit TAB or type "help".
http://api.myservice.com/v1:>

7.10 SSL Certificate Validation

If you generate a self-signed certificate for your server, by default the rest-shell will complain and refuse to connect. This is the default behavior of RestTemplate. To turn off certificate and hostname checking, use the ssl validate --enabled false command.

7.11 HTTP Basic authentication

There is also a convenience command for setting an HTTP Basic authentication header. Use auth basic --username user --pasword passwd to set a username and password to base64 encode and place into the Authorization header that will be part of the current session's headers.

You can clear the authentication by using the auth clear command or by removing the Authorization header using the headers clear command.

7.12 Commands

The rest-shell provides the following commands:

Table 7.1. rest-shell commands
Command Description

baseUri { uri }

Set the base URI used for this point forward in the session. Relative URIs will be calculated relative to this setting.

discover [ [--rel rel ] | [ path ] ]

Find out what resources are available at the given URI. If no URI is given, use the baseUri.

follow [ [--rel rel ] | [ path ] ]

Set the baseUri to the URI assigned to this given rel or path but do not discover resources.

list [ [--rel rel ] | [ path ] ] [--params JSON ]

Find out what resources are available at the given URI.

headers set {--name name } {--value value }

Set an HTTP header for use from this point forward in the session.

headers clear

Clear all HTTP headers set during this session.

headers list

Print out the currently-set HTTP headers for this session.

history list

List the URIs previously set as baseUris during this session.

history go [ num ]

Jump to a URI by pulling one from the history.

var clear

Clear this shell's variable context.

var get [--name name ] [--value expression ]

Get a variable from this shell's context by name or evaluate a shell expression.

var list

List variables currently set in this shell's context.

var set

Set a variable in this shell's context.

up

Traverse one level up in the URL hierarchy.

get [ [--rel rel ] | [ path ] ] [--follow true | false] [--params JSON ] [--output filename ]

HTTP GET from the given path. If --follow true is set, then follow any redirects automatically. If --output filename is set, output the the response into the given file.

post

HTTP POST to the given path, passing JSON given in the --data parameter.

put

HTTP PUT to the given path, passing JSON given in the --data parameter.

delete

HTTP DELETE to the given path.

auth basic

Set an HTTP Basic authentication token for use in this session.

auth clear

Clear the Authorization header currently in use.

ssl validate

Disable certificate checking to work with self-signed certificates.