Requests

One of the most powerful and commonly used actions in hyperpotamus is the request action. The request action describes an HTTP request to be sent (including the path, host, verb, body, method, and any headers) and then a series of one or more actions to be executed to analyze the response.

The simplest form of the request action is:

- request: http://somesite.com/path

which will execute a GET request with no special headers or parameters.

A more complete form of the request action is:

- request:
    url: http://somesite.com/path
    method: POST
    headers:
      header1: value1
    form: # (or json:)
      key1: value1
      key2: value2
  response:
    - {action1}
    # ...
    - {actionN}

Request properties

Some of the most common things to set on a request include cookies, json/form data, querystring parameters, the request method/verb, authentication data, proxy information, timeout settings, and redirect handling options.

Any request properties will be interpolated by hyperpotamus to replace any <% macros %> that are included. Using dynamic macros in the request properties is one of the most significant features of hyperpotamus. Any of the request properties may contain dynamic macro values.

- request:
   url: http://somesite.com/books/
   method: PUT
   json:
     book_id: <% book_isbn %>
     title: <% title %>
     author: <% author %>

The request action uses the request module. For full documentation on the parameters and values that can set on the request, see the module documentation.

Setting default request properties

If the session context contains an object with the key "request_defaults", then any properties on that request_defaults object will be merged into the request object before it is processed. This can be very useful to setup default settings such as adding a custom user-agent, an authentication header, or other options common to each request you want to make. The request_defaults can be updated at any point in the script and will take effect for all subsequent requests.

- request:
   url: http://somesite.com/oauth_excahnge
   json:
    refresh_token: <% refresh_token %>
  response:
   - status: 200
   - json:
      access_token: "$.access_token"
   - set:
      request_defaults:
       auth:
        bearer: <% access_token %>
       headers:
        x-custom-header: special sauce 

# From here on out, all requests will use the access token and custom header
- request: http://somesite.com/books/<% book_isbn | urlencode %>

By default, hyperpotamus uses the user-agent string:

Hyperpotamus/[VERSION] (+http://github.com/pmarkert/hyperpotamus)

This makes it easy for web-servers to identify and see that a request is coming from hyperpotamus. Most of the time, this is not a problem, but in some cases, you may need to override the default user-agent.

Response actions

Any action(s) under the response property will be executed once the response is received. Many hyperpotamus actions are specifically designed to analyze responses. In fact, some of these actions only work when used as a response action.

The primary response-specific actions include:

• status
• text
• regex
• json (* also has support for accessing an arbitrary target)
• jquery
• xpath
• body
• headers
• save

For more information about these actions, see the corresponding documentation.

Default Response Actions

By default, if a request does not have a corresponding response property, then the default response actions will be applied. Typically this is just a check to see if the status code of the response (after following any redirects) was 200 OK. The default actions can be modified using the response_defaults action.

The default value for response_defaults is equivalent to:

- response_defaults:
   - status: 200

To override the default actions, for example, to check to make sure the text "Error" does not appear in the response:

- response_defaults:
   - not: 
      text: Error

The response_defaults can be updated throughout the course of processing a script and the new values will take effect for any further requests executed.