- Docs
- Reference
- Step reference
- API Request step
API Request step
The API Request step sends an HTTP request in the middle of a test: create test data before a UI flow, read a token, or check that the backend stored what the UI showed. It works in web, mobile and desktop projects.
In short
On this page you can
- Add a request from your API Requests library or paste a curl command.
- Edit method, URL, body, authorization, params and headers for this step.
- Try the request with Send and click response values to save them.
- Save
@statusor a header into a variable and assert on it. - Use variables in the URL, body, headers and token.
How to use it
- Click API and pick a request in Select API Request, or use Create from curl.
- Select the step and adjust the request in the right panel.
- Click Send, then click a value in the response to add a JSON Paths row.
- Name each row’s key, for example
token; later steps use{{tc:token}}. - Add an Assertion on
{{tc:status}}so a 4xx or 5xx fails the test.
Add an API step#
Open the picker
Click API in the step toolbar. The dialog Select API Request lists the requests of the project’s API Requests library. Search with “Search by name, URL or method...”.
Pick a request, or paste curl
Click the add icon (Add Step) on a request’s row. Or click Create from curl, paste a curl command and click Create & Add: a new API Request is created in the library and added as a step.
The step shows the chip API. It gets its own copy of the request; editing the step does not change the library request.
Adjust the request
Select the step. In the right panel edit the method, the URL and the tabs Body, Authorization, Params and Headers.
Try it and save values
Click Send. Click a value in the response to add it under JSON Paths, and give it a key. See Save values from the response.
Check the result
Add an Assertion after the step. See Check the status code.
The request#
| Part | Options | Notes |
|---|---|---|
| Method | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS | The runner sends only GET, POST, PUT, PATCH and DELETE. HEAD and OPTIONS can be saved but fail at run time with “Unsupported HTTP method”. |
| URL | Full address | Required (“API URL is required”). Variables allowed: {{tc:baseUrl}}/orders/{{tc:orderId}}. |
| Body | form-data rows, or raw as JSON, XML, HTML, Text or JavaScript | Variables are resolved in the body. The editor offers form-data, but runs ignore it: a run sends only the raw body, as JSON, and a body that is not JSON goes out as one JSON text in quotes (Bodies in runs). |
| Authorization | None, Bearer Token, Basic Auth, Inherit from parent | A token can be a variable: {{tc:token}}. The editor offers all four, but runs apply only Bearer Token; for a basic login, add an Authorization header (Authorization in runs). |
| Params | Key and value rows | Added to the URL as the query string. |
| Headers | Key and value rows | For example Content-Type: application/json. |
Try the request with Send#
Send runs the request now and shows the status code and the response. It is sent from the SmartestQA server, not from your agent, so it cannot reach APIs inside your company network; the test run itself can, when it runs on your agent.
- If the request contains variables, the dialog Test values asks for a value for each. “These variables get their value during the test run. Enter a value to try the request; values are not saved.” Empty fields are sent as empty text.
- To send from here, the URL must start with
http://orhttps://. A URL that starts with a variable can still be saved and run. - Messages: “Request successful”, “The request timed out (30s). The target did not respond.”, “Host not found. Please check the URL.”, “Connection refused. The target is not reachable.”, “The request could not be completed. Please try again.”
Save values from the response#
Each row under JSON Paths has a key (the variable name) and a path. After the step runs, the value at the path is saved as {{tc:key}}.
- Click to add. After Send, “Click on any value in the response to extract its JSON path.” For XML responses, pick the node in the XML view.
- Add by hand. The plus icon adds an empty row: “Add JSON path manually (use when the API cannot be reached from here)”.
- The preview under a row shows what the path finds in the last response: “No match in the response - no value will be stored”, or how many matches there are (“the first one is used”).
| Path | Reads | Example result |
|---|---|---|
data.token or $.data.token | A JSON field | eyJhbGciOi… |
items.0.id or items[0].id | A field of the first array item (counting from 0) | 1042 |
/order/status | An XML node (paths starting with / are XPath) | SHIPPED |
@status | The HTTP status code | 201 |
@header:Location | A response header | /orders/1042 |
Rows need both parts: “Fill in the key and the JSON path, or remove this row”. A path that cannot work is refused on save: “JSON path is invalid and cannot work at runtime”. If a path finds nothing at run time, the log notes that the key was not found and the variable is not set.
Check the status code#
Any HTTP answer is a passed step
The API step ends as SUCCESS for every status code, including 400, 401, 404 and 500. Only a timeout, an SSL error or a refused connection ends it as ERROR, and even then the test case continues. To make the test fail on a wrong status, save it and assert on it.
Step 3 API POST {{tc:baseUrl}}/api/orders
JSON Paths: status ← @status orderId ← data.id
Step 4 Assertion actual {{tc:status}} Equals expected 201
Step 5 Assertion actual {{tc:orderId}} Is Not EmptyFor negative tests, the same pattern checks that a call is refused: assert {{tc:status}} Equals 403.
At run time#
- The request is sent from the machine that runs the test (the server or your agent), with a fixed timeout of 30 seconds.
- TLS certificates are always verified. A self-signed certificate makes the step end as ERROR.
- Variables in the URL, body, headers, query parameters and Bearer token are resolved first.
- The report keeps the request and the response of the step (the response is shortened to 5,000 characters).
- API steps are the only step type allowed next to JMeter and k6 steps. A load test can be generated from them; see Load tests.
If something goes wrong#
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai