API Explorer

LicenseCustom add-onDetails

Show for

Any licenseInt4 Shield Lite

Feature or limit	Int4 Shield Lite
API testing	Add-on

Anything a license model does not include can be added through a custom license. The license installed for you is shown in the app under Profile → License. All features by license

Overview

The API Explorer is a workbench for trying out HTTP APIs. You build a request, send it to one of your HTTP systems under test, and see straight away what came back and whether it passed the checks you defined. Every send is recorded, so you always have evidence of what was called, with which data, and what the system answered.

It is the exploratory counterpart to automated test cases. While you are still finding out how an API behaves — which parameters it needs, what a good answer looks like — the explorer is quicker than building a test case. Once a request behaves as expected, promote it: Int4 Suite creates an HTTP Call automation object and a test case from it, with the response you saw as the expected result, so the exploration turns into regression coverage without retyping anything.

Requests live in folders, just like test cases. A folder decides the project scope (who may see and send its requests) and can name a group of systems; when a folder's group holds exactly one HTTP system, requests in it are sent there unless you pick another target. Requests are versioned: every save creates a new version you can go back to, and sending never changes a request.

You can also start requests from an OpenAPI specification — one request per operation — or from an existing HTTP Call automation object. Credentials come from the target system by default; authentication profiles let you store other credentials once and reuse them across requests without ever putting a password into a request.

Tasks

How to organise requests in folders

The folder tree on the left works like the one in the test case cockpit: create a folder with New folder, and change or delete one from its Folder actions menu. In a folder's details you can set its Project scope and its Group, or inherit both from the parent folder. A folder that still holds requests cannot be deleted.

How to create a request

1. Select a folder in the tree and select New Request.
2. Under Identification, enter a Name (unique in the folder) and optionally a Description and Tags.
3. Under Endpoint, choose the Method and enter the URL Path. The path is appended to the target system's URL. Write a path parameter as {name}, for example /orders/{orderId}.
4. Under Parameters, add the values the request needs with Add parameter: a path parameter fills its placeholder, a query or header parameter is added to the call. Mark parameters as required where the call makes no sense without them.
5. Under Authentication, choose the Credentials: From the target system (default), Authentication profile — then pick the Authentication Profile — or None.
6. Under Body, enter the Body and its Content Type for methods that send one.
7. Optionally add checks under Assertions (see the next task).
8. Select Save Changes. The request is saved as version 1.

If the service needs a CSRF token for modifying calls (SAP OData services do), switch on Fetch CSRF Token under Endpoint. The token is fetched with the chosen CSRF Token Fetch Method from the CSRF Token URL, or from the request path itself when that field is empty.

How to check the response automatically

Under Assertions, select Add check and choose what the check looks at:

Check	Passes when
Status	The response status equals the expected number (100–599).
Response time	The call took no longer than the expected number of milliseconds.
Header	The named response header has the expected value.
Body	An XPath, JSONPath or regular expression on the response body finds the expected value. Leave the expected value empty to only require that the expression finds something.
Script	An Aster script returns TRUE.

Values are compared as text, so a JSON number 123 is expected as 123. Every send is judged against the checks of the version that was sent; a request without checks passes every send.

How to send a request

1. Open a saved request.
2. Pick the target system in the Target system field. Only HTTP systems are offered. You can leave it empty when the folder's group holds exactly one HTTP system.
3. Select Send. The response console shows Response — status, headers, body and the result of every check (Passed, Failed or Not run) — and Request as sent.

While you edit, Send sends the request as it stands in the editor without saving it; the console marks such a send as Unsaved changes. You can also send an earlier version while viewing it.

If the call gets no answer, the console shows No response with the reason. A send shown as Unknown was never recorded as finished — the call may still have reached the target.

How to send to a system that is not set up as a system under test

If you are allowed to, an Ad-hoc target… button appears next to the target picker.

1. Select Ad-hoc target…, enter the Destination and select Use target.
2. Send as usual. The typed-in host is shown as a chip; remove the chip to go back to a system under test.

Nothing you type here is saved. Stored credentials — an authentication profile or a parameter that reads a profile's secret — are never sent to a typed-in host.

How to review earlier sends

• The request's own sends are listed under History; open one to show it in the console.
• History in the navigation lists sends across all folders. Search by request name or path, or switch on Mine to see only your own sends. Open a send to see what went out and what came back, and use Open request to jump to the request.

Sends are kept permanently, even after the request is deleted.

How to change a request or go back to an earlier version

1. Open the request, select Edit, make your changes and select Save Changes. Every save creates a new version; you can describe it in Version Description.
2. To look at an earlier version, open it from Versions. A banner shows which version you are viewing.
3. To make it current again, select Restore This Version and confirm. The old content is copied into a new version. Back to Current Version leaves the version view.

How to import requests from an OpenAPI specification

1. Select the target folder in the tree and select Import from OpenAPI….
2. Upload an OpenAPI 3.x or Swagger 2.0 file (JSON or YAML). Switch on CSRF token handling if modifying calls need a CSRF token, then select Parse specification.
3. Check the Base path — it is put in front of every path, relative to the HTTP system — and select the operations to import. Rows with a name problem are marked.
4. Switch on Body from example to fill each request body with the example from the specification.
5. Select the import button. Either all selected requests are created or none.

How to start a request from an automation object

1. Select the target folder and select From automation object….
2. Choose the HTTP Call Automation object and optionally a Request name, then select Create request.

The request starts from the automation object's template and stays linked to it. Its path dimensions become parameters. The body and credentials are not part of a template; add them yourself.

How to turn a request into a test case

1. Send the request so that it gets a response, and save it if you sent unsaved changes — a send of unsaved changes cannot be promoted.
2. Select Promote.
3. In Promote to test case, choose the Response to expect (the latest send with a response is preselected), the Test case name and the test case Folder. Optionally choose an Execution Group; leave it empty to run against whatever the folder resolves to.
4. Under Automation object, choose Use an existing one or Create a new one and, for a new one, its name. If the existing automation object differs from the request, tick Update the automation object with the request's template (new version) to give it a new version, or pick another one.
5. Optionally tick Pin the response headers the target answered with and add Tags.
6. Review What will be written — what is pinned, what is left out and any warnings — and select Promote. The new test case is linked from the request.

The request as it went out becomes the test case's input and the response becomes its expected result, compared by the request's checks. A request that reads a parameter from an authentication profile cannot be promoted, because a test case cannot carry a stored secret; put the credential on the system under test instead.

How to store credentials in an authentication profile

1. Select Auth Profiles in the navigation and select New Profile.
2. Enter a Name (unique), optionally a Description, and a Project Scope. A profile without a scope can be used by everyone.
3. Under Credentials, choose the type — Basic Authentication, OAuth2 Client Credentials, API Key or No Authentication — and enter the credentials.
4. Save. The secret is stored in the secret manager and never shown again; when editing, leave the field empty to keep it.

Use the profile on a request through Credentials, or let a single parameter (for example an API key header) take its value from the profile with Secret from profile. A profile cannot be deleted while a request still uses it.

Field reference

Request

Field	Description
Name	Up to 100 characters, unique within the folder.
Description	Up to 200 characters.
Folder	Where the request lives. Moving it to another folder changes who may see and send it.
Automation object	The HTTP Call automation object the request was started from or promoted into, if any.
Method, URL Path	HTTP method and path, appended to the target system's URL.
Parameters	Name, In (path, query or header), Required, Value or a secret from a profile (not both), Description. A path parameter needs a matching {name} placeholder in the path.
Credentials	From the target system, Authentication profile or None.
Body, Content Type	The payload and its content type.
Fetch CSRF Token	Fetch a CSRF token before the call, with CSRF Token Fetch Method and CSRF Token URL.
Assertions	The checks every send is judged against.

Send and history

Field	Description
Method, Request	What was sent. A send whose request was deleted keeps the request's name.
Sent	When the send was made, and by whom (shown on the send).
Status	The HTTP status, or No response / Unknown.
Checks	How many checks passed, with each check's expected and actual value.

Authentication profile

Field	Description
Name	Up to 100 characters, unique across all profiles.
Description	Up to 200 characters.
Project Scope	Who may see and use the profile. Empty: everyone.
Authentication	Authentication type and credentials, as on a system under test.

Tips & edge cases

• Values that look like credentials are masked in the history. Header and query values named like Authorization, Cookie, X-API-Key or ending in token, secret, password or key are stored as [secure]. The body is stored exactly as typed, so do not paste secrets into it — use a profile or a profile-secret parameter instead. The editor warns when a parameter name looks like a credential.
• One send at a time per request. While your send of a request is running, a second one is refused; you can also have only a limited number of sends running at once (five by default), and the whole installation has a shared limit. A send gives up after 50 seconds.
• Large responses. Response bodies are kept up to 5 MB; anything longer is cut, and such a send cannot be promoted.
• Which system receives the call. The picked target system, or else the only HTTP system in the folder's group. If the group has none or more than one, pick a target.
• Sends are evidence. The history is never deleted, not even with the request. Anyone with read access in the project scope the send was made in can open it.
• Promoting again is allowed. A request can be promoted several times; the dialog tells you about earlier test cases made from it.
• Values copied into the test case. If a parameter with a credential-like name has a typed value, promote copies it into the test case and warns you; prefer storing credentials on the system under test.

Related features

• Systems Under Test — the HTTP systems requests are sent to, and their credentials.
• Automation Objects — HTTP Call automation objects created by promote or used as a starting point.
• Test case cockpit — where promoted test cases live and run.
• Scripts — Aster scripts used by script checks.

Prerequisites & permissions

About permissions. What you can see and do is decided by the roles assigned to your user. Each role bundles permission groups, and each permission group allows activities — Read, Write, Delete, Execute and, for schedules, Change owner — on a kind of record (for example Test Case, Automation Object, System Under Test). A role grants its groups per project scope, so you may be allowed to change records in one project but only view, or not see, those of another.

If a button is disabled, a page says you don't have access, or a list comes back empty, missing permissions are the most likely cause — or, for whole product areas, the installed licence. You can review your own access under Profile → My access; an administrator can change your roles under IAM → Users.

The API Explorer is available when API testing is included in your licence. Permissions follow the project scope of the folder a request lives in:

• Folder: Read — show the folder tree; Folder: Write and Folder: Delete create, change and delete folders, as in the test case cockpit.
• API Explorer: Read — browse requests, see sends and authentication profiles.
• API Explorer: Write — create, edit, import and restore requests; create and edit authentication profiles.
• API Explorer: Delete — delete requests and authentication profiles.
• API Explorer: Execute — send requests. Sending also needs System Under Test: Read on the target system.
• API explorer ad-hoc target: Execute — send to a typed-in host instead of a system under test. Usually reserved for administrators.
• Promoting needs API Explorer: Write plus Folder: Write and Test Case: Write in the target test case folder, and Automation Object: Write when an automation object is created or updated (Read when an existing one is reused). Your licence must allow HTTP Call automation objects and test case creation.

Was this page helpful?Send a quick note to the documentation team.

0 / 2000 characters