Configuring HTTP requests in HTTP Client
Your request's HTTP method can be set using the dropdown box near the text field for the URL. The supported methods are:
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://email@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.
As seen in the example above, a URL can have query parameters. These query parameters are the key-value pairs that come
? 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.
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
Unlike query parameters, path parameters do not have a checkbox that allows you to choose whether to send it or not.
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.
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.
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.
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.
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:
form-data-type of request body can hold multiple key-value pairs whose value can be either text or binary.
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 request body content is similar to a
form-data payload except that its
name-value pairs accept text values only.
A request can be configured to send a text-only payload, which is often written in a markup format. The HTTP Client
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.
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.
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.
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.
The Description field can be used for documenting your request headers. It is considered metadata and is not sent as part of any request.
A request cookie allows the client to send information back to the server. Just like headers, you can have multiple cookies.
The Cookie Manager allows you to manage all cookies which have been sent back by servers you have sent a request to.
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.
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.
With this scheme, the client will send an
Authorization header with a Base64-encoded string of
which means that this authentication type requires the account username and password.
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
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.
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
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 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.
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.
[[ssn]] creates a mock social security number string;
[[address]] is for generating a random, fake
[[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.
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.
Uniform Resource Identifier. (n.d.) In Wikipedia. Retrieved February 20, 2019, from https://en.wikipedia.org/wiki/Uniform_Resource_Identifier ↩