Permalink
Fetching contributors…
Cannot retrieve contributors at this time
444 lines (350 sloc) 24.3 KB

Examples

Here are a few annotated htty session transcripts to get you started.

Querying a web service

This simple example shows how to explore a read-only web service with htty.

ESV Bible Web Service example #1

$ htty esvapi.org
*** Welcome to htty, the HTTP TTY. Heck To The Yeah!
http://esvapi.org/> get
*** Type fol[low] to follow the 'Location' header received in the response
301 Moved Permanently -- 6 headers -- 373-character body
http://esvapi.org/> follow
http://www.esvapi.org/> 

You can point htty at a complete or partial web URL. If you don’t supply a URL, http://0.0.0.0/ (port 80) will be used. You can vary the protocol scheme, userinfo, host, port, path, query string, and fragment as you wish.

The htty shell prompt shows the address of the current request.

The get command is one of seven HTTP request methods supported. A concise summary of the response is shown when you issue a request.

You can follow redirects using the follow command. No request is made until you type a request command such as get or post.

ESV Bible Web Service example #2

http://www.esvapi.org/> cd /v2/rest/nonexistent/path
http://www.esvapi.org/v2/rest/nonexistent/path> get
404 Not Found -- 5 headers -- 369-character body
http://www.esvapi.org/v2/rest/nonexistent/path> cd ../../passageQuery
http://www.esvapi.org/v2/rest/passageQuery> 

You can tweak segments of the address at will. Here we are navigating the site’s path hierarchy, which you can do with relative as well as absolute pathspecs.

ESV Bible Web Service example #3

http://www.esvapi.org/v2/rest/passageQuery> query-set key IP
http://www.esvapi.org/v2/rest/passageQuery?key=IP> query-set passage 'Luke 5:3-6'
http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6> query-set output-format plain-text
http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6&output-format=plain-text> get
200 OK -- 10 headers -- 565-character body
http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6&output-format=plain-text> body
=======================================================
Luke 5:3-6
    [3]Getting into one of the boats, which was Simon's, he asked him to
put out a little from the land. And he sat down and taught the people
from the boat. [4]And when he had finished speaking, he said to Simon,
"Put out into the deep and let down your nets for a catch." [5]And Simon
answered, "Master, we toiled all night and took nothing! But at your word
I will let down the nets." [6]And when they had done this, they enclosed
a large number of fish, and their nets were breaking. (ESV)
http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6&output-format=plain-text> 

Here we add query-string parameters. Notice that characters that require URL encoding are automatically URL-encoded (unless they are part of a URL-encoded expression).

The headers-response and body-response commands reveal the details of a response.

ESV Bible Web Service example #4

http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6&output-format=plain-text> address http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6&output-format=plain-text&include-passage-horizontal-lines=false&include-passage-references=false&include-verse-numbers=false&include-short-copyright=false&line-length=0
http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6&output-format=plain-text&include-passage-horizontal-lines=false&include-passage-references=false&include-verse-numbers=false&include-short-copyright=false&line-length=0> get
200 OK -- 9 headers -- 474-character body
http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6&output-format=plain-text&include-passage-horizontal-lines=false&include-passage-references=false&include-verse-numbers=false&include-short-copyright=false&line-length=0> body
Getting into one of the boats, which was Simon's, he asked him to put out a little from the land. And he sat down and taught the people from the boat. And when he had finished speaking, he said to Simon, "Put out into the deep and let down your nets for a catch." And Simon answered, "Master, we toiled all night and took nothing! But at your word I will let down the nets." And when they had done this, they enclosed a large number of fish, and their nets were breaking.
http://www.esvapi.org/v2/rest/passageQuery?key=IP&passage=Luke%205:3-6&output-format=plain-text&include-passage-horizontal-lines=false&include-passage-references=false&include-verse-numbers=false&include-short-copyright=false&line-length=0> quit
*** Happy Trails To You!
$ 

There was some cruft in the web service’s response (a horizontal line, a passage reference, verse numbers, a copyright stamp, and line breaks). We eliminate it by using API options provided by the web service we’re talking to.

We do a Julia Child maneuver and use the address command to change the entire URL, rather than add individual query-string parameters one by one.

Exit your session at any time by typing quit or hitting Ctrl-D.

Working with cookies

The next example demonstrates htty’s HTTP Secure support and cookies features, as well as how to review and revisit past requests.

Google example #1

https://www.google.com/search?q=Ruby+programming+language> get
*** Type cookies-u[se] to use cookies offered in the response
*** Type fol[low] to follow the 'Location' header received in the response
302 Found -- 8 headers* -- 260-character body
https://www.google.com/search?q=Ruby+programming+language> headers-response
        Location: https://encrypted.google.com/search?q=Ruby+programming+language
   Cache-Control: private
    Content-Type: text/html; charset=UTF-8
     Set-Cookie:* O=HAI.; I=CAN; HAS=PRAIVASY?; G00G=RULZ!
            Date: Tue, 28 Sep 2010 19:57:23 GMT
          Server: gws
  Content-Length: 260
X-Xss-Protection: 1; mode=block
https://www.google.com/search?q=Ruby+programming+language> follow
https://encrypted.google.com/search?q=Ruby+programming+language> 

The https:// scheme and port 443 imply each other, just as the http:// scheme and port 80 imply each other. If you omit the scheme or the port, it will default to the appropriate value.

Notice that when cookies are offered in a response, a bold asterisk (it looks like a cookie) appears in the response summary. The same cookie symbol appears next to the Set-Cookie header when you display response headers.

Google example #2

https://encrypted.google.com/search?q=Ruby+programming+language> headers-request
User-Agent: htty/1.1.0
https://encrypted.google.com/search?q=Ruby+programming+language> cookies
https://encrypted.google.com/search?q=Ruby+programming+language> cookies-use
*** 4 cookies now in use
https://encrypted.google.com/search?q=Ruby+programming+language> headers-request
User-Agent: htty/1.1.0
   Cookie:* O=HAI.; I=CAN; HAS=PRAIVASY?; G00G=RULZ!
https://encrypted.google.com/search?q=Ruby+programming+language> cookies
   O: HAI.
   I: CAN
 HAS: PRAIVASY?
G00G: RULZ!
https://encrypted.google.com/search?q=Ruby+programming+language> 

The cookies-use command copies cookies out of the response into the next request. The cookie symbol appears next to the Cookie header when you display request headers.

Google example #3

https://encrypted.google.com/search?q=Ruby+programming+language> get
200 OK -- 8 headers* -- 41111-character body
https://encrypted.google.com/search?q=Ruby+programming+language> history
1 GET https://www.google.com/search?q=Ruby+programming+language -- 1 header -- empty body
  302 Found -- 8 headers* -- 260-character body
2 GET https://www.google.com/search?q=Ruby+programming+language -- 2 headers* -- empty body
  200 OK -- 8 headers* -- 41111-character body
https://encrypted.google.com/search?q=Ruby+programming+language> headers-request
User-Agent: htty/1.1.0
   Cookie:* O=HAI.; I=CAN; HAS=PRAIVASY?; G00G=RULZ!
https://encrypted.google.com/search?q=Ruby+programming+language> reuse 1
*** Using a copy of request #1
https://encrypted.google.com/search?q=Ruby+programming+language> headers-request
User-Agent: htty/1.1.0
https://encrypted.google.com/search?q=Ruby+programming+language> 

An abbreviated history is available through the history command. Information about requests in the history includes request method, URL, number of headers (and a cookie symbol, if cookies were sent), and the size of the body. Information about responses in the history includes response code, number of headers (and a cookie symbol, if cookies were received), and the size of the body.

Note that history contains only numbered HTTP request and response pairs, not a record of all the commands you enter.

The reuse command makes a copy of the headers and body of an earlier request for you to build on.

Understanding complex HTTP conversations at a glance using history

Now we’ll look at htty’s HTTP Basic Authentication support and learn how to display unabbreviated transcripts of htty sessions.

Assume that we have the following Sinatra application listening on Sinatra’s default port, 4567.

require 'sinatra'

get '/all-good' do
  [200, [['Set-Cookie', 'foo=bar; baz']], 'Hello World!']
end

put '/huh' do
  [404, 'What?']
end

delete '/hurl' do
  [500, 'Barf!']
end

post '/submit-novel' do
  redirect '/all-good'
end

This application expects GET and POST requests and responds in various contrived ways.

Sinatra application example #1

http://0.0.0.0:4567/all-good> get
*** Type cookies-u[se] to use cookies offered in the response
200 OK -- 6 headers* -- 12-character body
http://0.0.0.0:4567/all-good> cookies-use
*** 2 cookies now in use
http://0.0.0.0:4567/all-good> cd /huh
http://0.0.0.0:4567/huh> put
404 Not Found -- 5 headers -- 5-character body
http://0.0.0.0:4567/huh> userinfo-set htty@nilsjonsson.com secret
http://htty%40nilsjonsson.com:secret@0.0.0.0:4567/huh> cd /hurl
http://htty%40nilsjonsson.com:secret@0.0.0.0:4567/hurl> delete
500 Internal Server Error -- 5 headers -- 5-character body
http://htty%40nilsjonsson.com:secret@0.0.0.0:4567/hurl> cookies-remove-all
http://htty%40nilsjonsson.com:secret@0.0.0.0:4567/hurl> userinfo-unset
http://0.0.0.0:4567/hurl> body-set
*** Enter two blank lines, or hit Ctrl-D, to signify the end of the body
If a body

meet a body

comin' through the rye


http://0.0.0.0:4567/hurl> header-set Author 'J. D. Salinger'
http://0.0.0.0:4567/hurl> cd /submit-novel
http://0.0.0.0:4567/submit-novel> post
*** Type fol[low] to follow the 'Location' header received in the response
302 Found -- 6 headers -- empty body
http://0.0.0.0:4567/submit-novel> 

When you change the userinfo portion of the address, or the entire address, the appropriate HTTP Basic Authentication header is created for you automatically. Notice that characters that require URL encoding are automatically URL-encoded (unless they are part of a URL-encoded expression).

When userinfo is supplied in a request, a bold mercantile symbol ( @ ) appears next to the resulting Authorization header when you display request headers (see below).

Type body-set to enter body data, and terminate it by entering two consecutive blank lines, or by hitting Ctrl-D. The body will only be sent for POST and PUT requests. The appropriate Content-Length header is created for you automatically (see below).

Different response codes are rendered with colors that suggest their meaning:

  • Response codes between 200 and 299 appear black on green to indicate success
  • Response codes between 300 and 399 appear white on blue to indicate redirection
  • Response codes between 400 and 499 appear white on red to indicate failure
  • Response codes between 500 and 599 appear flashing black on yellow to indicate a server error

Sinatra application example #2

http://0.0.0.0:4567/submit-novel> history-verbose
1 GET http://0.0.0.0:4567/all-good -- 1 header -- empty body

User-Agent: htty/1.1.0

200 OK -- 6 headers* -- 12-character body

  Content-Type: text/html
Content-Length: 12
        Server: WEBrick/1.3.1 (Ruby/1.9.3/2010-09-25)
          Date: Tue, 28 Sep 2010 21:10:58 GMT
    Connection: Keep-Alive
   Set-Cookie:* foo=bar; baz

Hello World!
------------------------------------------------------------------------------
2 PUT http://0.0.0.0:4567/huh -- 3 headers* -- empty body

    User-Agent: htty/1.1.0
Content-Length: 0
       Cookie:* foo=bar; baz

404 Not Found -- 5 headers -- 5-character body

  Content-Type: text/html
Content-Length: 5
        Server: WEBrick/1.3.1 (Ruby/1.9.3/2010-09-25)
          Date: Tue, 28 Sep 2010 21:11:05 GMT
    Connection: Keep-Alive

What?
------------------------------------------------------------------------------
3 DELETE http://htty%40nilsjonsson.com:secret@0.0.0.0:4567/hurl -- 3 headers* -- empty body

    User-Agent: htty/1.1.0
       Cookie:* foo=bar; baz
Authorization:@ Basic aHR0eUBuaWxzam9uc3NvbjpzZWNyZXQ=

500 Internal Server Error -- 5 headers -- 5-character body

  Content-Type: text/html
Content-Length: 5
        Server: WEBrick/1.3.1 (Ruby/1.9.3/2010-09-25)
          Date: Tue, 28 Sep 2010 21:12:17 GMT
    Connection: Keep-Alive

Barf!
------------------------------------------------------------------------------
4 POST http://0.0.0.0:4567/submit-novel -- 3 headers -- 46-character body

    User-Agent: htty/1.1.0
Content-Length: 46
        Author: J. D. Salinger

If a body

meet a body

comin' through the rye

302 Found -- 6 headers -- empty body

  Content-Type: text/html
      Location: http://0.0.0.0:4567/all-good
Content-Length: 0
        Server: WEBrick/1.3.1 (Ruby/1.9.3/2010-09-25)
          Date: Tue, 28 Sep 2010 21:13:44 GMT
    Connection: Keep-Alive
http://0.0.0.0:4567/submit-novel> 

As with the abbreviated history demonstrated earlier, verbose history shows a numbered list of requests and the responses they elicited. All information exchanged between client and server is shown.

Getting help

You can learn how to use htty commands from within htty.

htty’s built-in help

http://0.0.0.0/> help

                                   Navigation

  a[ddress] ADDRESS                             Changes the address of the
                                                request
  cd PATH                                       Alias for path[-set]
  fol[low]                                      Changes the address of the
                                                request to the value of the
                                                response's 'Location' header
  fragment-c[lear]                              Alias for
                                                fragment-u[nset]
  fragment-s[et] FRAGMENT                       Sets the fragment of the
                                                request's address
  fragment-u[nset]                              Removes the fragment from the
                                                request's address
  history                                       Displays previous
                                                request-response activity in
                                                this session
  history-[verbose]                             Displays the details of previous
                                                request-response activity in
                                                this session
  ho[st-set] HOST                               Changes the host of the
                                                request's address
  path[-set] PATH                               Changes the path of the
                                                request's address
  por[t-set] PORT                               Changes the TCP port of the
                                                request's address
  query-a[dd] NAME [VALUE [NAME [VALUE ...]]]   Adds query-string parameters to
                                                the request's address
  query-c[lear]                                 Alias for
                                                query-unset-[all]
  query-r[emove] NAME [VALUE]                   Removes query-string parameters
                                                from the end of the request's
                                                address
  query-s[et] NAME [VALUE [NAME [VALUE ...]]]   Sets query-string parameters in
                                                the request's address
  query-unset NAME [VALUE]                      Removes query-string parameters
                                                from the request's address
  query-unset-[all]                             Clears the query string of the
                                                request's address
  r[euse] INDEX                                 Copies a previous request by the
                                                index number shown in history
  sc[heme-set] SCHEME                           Changes the scheme (protocol
                                                identifier) of the request's
                                                address
  userinfo-c[lear]                              Alias for
                                                userinfo-u[nset]
  userinfo-s[et] USERNAME [PASSWORD]            Sets the userinfo of the
                                                request's address
  userinfo-u[nset]                              Removes the userinfo from the
                                                request's address

                               Building Requests

  body-c[lear]                                  Alias for body-u[nset]
  body-request                                  Displays the body of the request
  body-s[et]                                    Sets the body of the request
  body-u[nset]                                  Clears the body of the request
  cookie-a[dd] NAME [VALUE]                     Alias for cookies-a[dd]
  cookie-r[emove] NAME                          Alias for cookies-remove
  cookies                                       Displays the cookies of the
                                                request
  cookies-a[dd] NAME [VALUE]                    Adds a cookie to the request
  cookies-c[lear]                               Alias for
                                                cookies-remove-[all]
  cookies-remove NAME                           Removes from the request the
                                                last cookie having a particular
                                                name
  cookies-remove-[all]                          Removes all cookies from the
                                                request
  cookies-u[se]                                 Uses cookies offered in the
                                                response
  form                                          (Help for form is not
                                                available)
  form-a[dd]                                    (Help for form-a[dd] is
                                                not available)
  form-c[lear]                                  Alias for
                                                form-remove-[all]
  form-remove                                   (Help for form-remove is
                                                not available)
  form-remove-[all]                             (Help for
                                                form-remove-[all] is not
                                                available)
  header-s[et] NAME VALUE                       Alias for headers-s[et]
  header-u[nset] NAME                           Alias for headers-unset
  headers-c[lear]                               Alias for
                                                headers-unset-[all]
  headers-req[uest]                             Displays the headers of the
                                                request
  headers-s[et] NAME VALUE                      Sets a header of the request
  headers-unset NAME                            Removes a header of the request
  headers-unset-[all]                           Removes all headers from the
                                                request

                                Issuing Requests

  d[elete]                                      Alias for http-d[elete]
  g[et]                                         Alias for http-g[et]
  http-d[elete]                                 Issues an HTTP DELETE using the
                                                current request
  http-g[et]                                    Issues an HTTP GET using the
                                                current request
  http-h[ead]                                   Issues an HTTP HEAD using the
                                                current request
  http-o[ptions]                                Issues an HTTP OPTIONS using the
                                                current request
  http-po[st]                                   Issues an HTTP POST using the
                                                current request
  http-pu[t]                                    Issues an HTTP PUT using the
                                                current request
  http-t[race]                                  Issues an HTTP TRACE using the
                                                current request
  pos[t]                                        Alias for http-po[st]
  pu[t]                                         Alias for http-pu[t]

                              Inspecting Responses

  body[-response]                               Displays the body of the
                                                response
  headers[-response]                            Displays the headers of the
                                                response
  st[atus]                                      Displays the status of the
                                                response

                                  Preferences

  ssl-verification                              Displays the preference for SSL
                                                certificate verification
  ssl-verification-of[f]                        Disables SSL certificate
                                                verification
  ssl-verification-on                           Reenables SSL certificate
                                                verification

                                 Miscellaneous

  e[xit]                                        Alias for qui[t]
  hel[p] [COMMAND]                              Displays this help table, or
                                                help on the specified command
  qui[t]                                        Quits htty
  un[do]                                        (Help for un[do] is not
                                                available)

http://0.0.0.0/> 

The help command takes an optional argument of the abbreviated or full name of a command.