Skip to content

Toro Cloud Dev Center


Configuring HTTP requests in HTTP Client

HTTP method

Your request's HTTP method can be set using the dropdown box near the text field for the URL. The supported methods are: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, and TRACE.

Request URL

The text field beside the HTTP method dropdown box is used to configure the URL where requests will be sent. The format of an HTTP/S URL is (example taken from Wikipedia1):

1
2
3
4
5
        userinfo     host        port
        ┌─┴────┐ ┌────┴────────┐ ┌┴┐
https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest
└─┬─┘ └───────┬────────────────────┘└─┬─────────────┘└──┬───────────────────────┘
scheme     authority                 path              query

As you type, the HTTP Client validates your URL. A small red 'x'-labeled circle will appear on the left side of the text field if the URL is invalid. A valid URL is required in order to send requests.

Invalid URL

As seen in the example above, a URL can have query parameters. These query parameters are the key-value pairs that come after the ? part of the URL. When a query parameter is present, the HTTP client will add it to the list of parameters under the Parameters tab. It will also appear with a checkbox, allowing you to choose whether to send the parameter with the request or not.

Query parameter shown in the Parameters tab

Aside from query parameters, the HTTP Client will also create entries in the Parameters tab for path variables. Path variables are defined using curly braces {}, like so: http://localhost:8080/api/sample/mock-api/forecast/{city}/{country}. Unlike query parameters, path parameters do not have a checkbox that allows you to choose whether to send it or not.

Path parameter shown in the Parameters tab

Parameters

The Parameters tab is where you can set values and add metadata to all defined query and path parameters of your request. Under this tab, you will see three columns: Name, Value, and Description. These are the properties you can set for every parameter.

Adding and removing parameters

To add a new query parameter, click the green '+'-labeled circular button located on the right wing of the Parameters tab (or press ). You can also directly edit the URL to add query and/or path parameters; these parameters will automatically show in the Parameters tab.

Likewise, to delete a query parameter, select the parameter and press the red 'x' circular button or use the key. You may also edit the URL and remove query and/or path parameters from there.

Edit the URL to add or remove path parameters

The only way to add or remove a path parameter is by editing the URL.

Adding and removing query and path parameters

Modifying parameters

To rename a parameter, set its value, or edit its description, double click on the cell with the value you want to edit. Once satisfied with your changes, press to submit. If the value you're typing is lengthy, you may expand the text area by clicking on the button on the right side of the cell. The button only appears when you are actively editing the cell.

Editing parameter values using the Parameters tab

You can also modify a parameter name by pressing key on a row, and modify the value by pressing , and you can also modify a parameter by right-clicking on it.

Editing query and path parameters with the context menu

Path variable renaming unsupported in the Parameters tab

Path variable renaming in the Parameters tab is not possible. In order to rename a path parameter, you must edit the URL.

Request body

The request payload can be set using the Body tab. Here, you may select the type of request payload and specify the actual request body content. Changing the body type also changes the Content-Type header in the Headers tab accordingly. The HTTP Client supports the following content types:

  • text/plain
  • form-data
  • application/json
  • application/xml
  • application/x-yaml
  • multipart/form-data
  • application/x-www-form-urlencoded
  • binary

Body tab

form-data payload

A form-data-type of request body can hold multiple key-value pairs whose value can be either text or binary.

`form-data` request body

To add a new key-value pair, click the green '+' button on the right side of the tab or simply press while focused on the Body tab. Meanwhile, select a row and use the red 'x' button to delete an entry or press .

To modify a field name, value, or description, double click its corresponding cell, enter your desired content, and press to apply your changes; press while editing to cancel. You can also modify a parameter name by pressing key on a row, and modify the value by pressing , and you can also modify a parameter by right-clicking on it.

Additionally, a field can be set to hold a binary value by checking the checkbox under the File column. Launch the file dialog to select which file to use for the binary field by double clicking the Value cell and then clicking the button which will appear on the right side of the cell; if you wish to use text data, enter the string as you normally would.

application/x-www-form-urlencoded payload

A application/x-www-form-urlencoded request body content is similar to a form-data payload except that its name-value pairs accept text values only.

Text payload

A request can be configured to send a text-only payload, which is often written in a markup format. The HTTP Client supports text/plain, application/json, application/xml, application/x-yaml.

You can change the type of data using the provided dropdown. The editor will render the string you type or paste with the corresponding syntax coloring according to the selected content type, and will also update the Content-Type header for you.

Binary payload

A request with a binary payload can be used to send any type of binary file to the receiving server. You can enter the file path manually or click the browse button to open the file dialog for selecting.

Request headers

A request header allows the client to relay more information about itself and/or specify what (resource) it will accept back from the server. A request can have multiple headers, which are essentially name-value pairs.

HTTP Client, Headers tab

To add a header, click the green '+' button on the right side of the tab. A new row in the table will appear where you may set the header's desired name and value. Alternatively, you can press instead of clicking the green button. You can double click the cells in order to edit their value any time you want. You can also modify a header name by pressing key on a row, and modify the value by pressing , and you can also modify a parameter by right-clicking on it.

To remove a header, select the header by clicking on it and then click the red 'x' button on the right to delete or press .

Content-assist is available for the header name; when editing a header name, press to show the list of possible header names. Use the up and down arrow key to navigate and press to select one. This is also true for header values.

Description field

The Description field can be used for documenting your request headers. It is considered metadata and is not sent as part of any request.

Request cookies

A request cookie allows the client to send information back to the server. Just like headers, you can have multiple cookies.

HTTP Client, Cookies tab

Cookie Manager

The Cookie Manager allows you to manage all cookies which have been sent back by servers you have sent a request to.

Authentication

Some web services are secured and would require access privileges. In order to let the server know that a user does indeed have access, we send the user's credentials along with the HTTP request. There are many ways to do this, and of all methods, the HTTP Client supports the most common authentication schemes: Basic, OAuth 1.0, and OAuth 2.0. In addition to these three, the HTTP Client also adds support for authentication via Martini sessions.

HTTP Client, Authentication tab

Authentication for requests is configured using the Authentication tab. There, you may select the type of authentication scheme you want to use and provide the credentials which will be sent with the request.

Learn how to secure your APIs!

Martini supports multiple ways of exposing APIs; the procedures required to secure your API depends on which method you have selected.

Basic

With this scheme, the client will send an Authorization header with a Base64-encoded string of username:password, which means that this authentication type requires the account username and password.

OAuth 1.0

OAuth authentication doesn't require your passwords to be shared to be able to access a resource. It specifies a process to authorize access to the users. This authentication type requires your:

  • consumer key
  • consumer secret
  • access token
  • token secret
  • signature method
  • timestamp
  • nonce
  • version
  • realm

OAuth 2.0

Like OAuth 1.0, it does not require usernames and passwords to be provided; instead, this authentication type requires your access token. Access tokens are short-lived tokens that gives you access to a resource.

Martini session

This authentication type uses an active Martini session ID to access a resource. The client sends an x-auth-token header with the given session ID. If you would like to a access a resource on a Martini instance that your user account is already connected to, you can use [[<server name>.currentSessionId]].

Using mock data

Instead of populating the required request data yourself, you can have the HTTP Client supply mock data on your behalf. To specify which fields should be mocked and which type of mock data should be provided, you will have to set the value of these fields so that they reference "variables". The syntax for variable references is [[variableName]] where variableName is the name of the variable to be used. They can be used in path and query parameters, headers, form data, text-based request bodies, URLs, and authentication fields.

Example data mocking

Below are requests that make use of the HTTP Client's data mocking feature. Both endpoints take in the inputs and incorporate them in the response with little to no processing.

Mocking a JSON request body

Mocking path parameters

Case sensitivity

There are variables whose names are case-sensitive but most are case insensitive.

There are about 40+ variables you can use. Each of these variables represent different types of mock data. For example, [[ssn]] creates a mock social security number string; [[address]] is for generating a random, fake address string; [[title]] produces a random book title string and so on.

View all available variables

To view all available variables, click the view available variables button near the top right corner of the Request panel.

View all variables

Content-assist

In the Parameters, Authentication, and Headers tab, once you enter [ in the value cell of a field, the list of available variables will show up. You may then use the arrow keys to sift through the options and/or press to finalize your selection. Content-assist however, is not accessible in the Body tab and URL text field.

Using content-assist


  1. Uniform Resource Identifier. (n.d.) In Wikipedia. Retrieved February 20, 2019, from https://en.wikipedia.org/wiki/Uniform_Resource_Identifier