Test APIs

APIs allow different software applications to communicate with each other and exchange information. In API testing, you send requests to the API and check the responses to ensure that everything works as expected.

Each API test requires one or more API messages. Each API message consists of a request and a response module. The request module contains the information required to send the API request, such as the method, endpoint, and payload. The response module validates the API response. Once you create a message, run it as a quick test or use it in your test cases.

Create an API message

To create an API message, follow these steps:

1. Go to Build > API messages to open the API playground.

2. Enter a clear name for your API message.

3. Set up your request:

   Field	Description
   Connection	You have two options to specify a connection. Select a connection you created on the API connections page. The Endpoint and Authorization fields become read-only. The base URL for a connection usually doesn't change. If you want to use the same endpoint for multiple requests, you can enter the path and query parameters in the Resource field. Enter Endpoint manually.
   Method	Select the HTTP method for your request.
   Endpoint	Enter the URL of your API endpoint. Tosca Cloud currently supports HTTP and HTTPS.
   Resource	When your Connection and base URL stay the same, edit this field instead of replacing the whole URL. Enter only the path and query that come after the base URL from the Endpoint. For example: /api/v1/orders/42?expand=lines. Tosca Cloud combines the Endpoint and Resource when you send the request.
   Payload	Enter the data to send.
   Headers	If needed, add extra information, such as content type or custom fields.
   Authorization	Enter basic credentials directly, or select an API connection that includes authentication. The API playground shows all other authentication types as read-only from the selected connection.

4. Define a Verification for the response message, if you want to check that the expected value matches the actual value.

5. Run a quick test to see whether your entries are valid and the verification returns the expected value.

6. Select Save.

Find all your API messages in the API playground panel:

Click to enlarge. API playground

Set up verification

Verifications help you test whether your service works as expected. You can verify message format, content, or response codes. Set the values you expect and compare them to what the service returns.

To set up verification:

1. Select an existing API message or create a new one.

2. In the Response section, select the Verification tab.

3. Select to add a verification.

4. Select the verification and configure the following properties:

   • Name - Enter a unique name for the verification.

   • Type - Select what to verify: Header, JsonPath, XPath, StatusCode, or ResponseTime.

   • Expression - Required for JsonPath or XPath. Enter your expression.

   • Operator - Select the comparison operator: Equal, NotEqual, Smaller, LessOrEqual, Greater, or GreaterOrEqual.

   • Value - Enter the expected value.

5. Select Save.

Click to enlarge. This example uses XPath to check a calculation result.

Run a quick test

To run a quick test, follow these steps:

1. Select an existing API message or create a new one.

2. Select Send from cloud. Use the option Send via agent to securely access APIs from within your environment, even when firewalls or network restrictions prevent direct connections. The personal agent safely delivers your data to the API.

3. Check your results on the Response tab:

   • Status code - Shows if your message reached the API successfully.

   • Verification results - Shows whether your verifications passed.

Click to enlarge. Response results

Create module attributes from API message elements

You can create module attributes from API message elements, such as the method or body. This allows you to control these elements in your test cases.

To create module attributes, follow these steps: 

1. Select the API message from which you want to create a module attribute. Then, switch to Build mode.

   In Build mode, you can see the request and response modules of the selected API message, including their current module attributes. The request module shows the Endpoint and Resource for the outgoing call.

2. Add API message elements to the Attribute preview panel in one of the following ways:

   • Elements with an icon: Select the icon next to an element.

   • Payload elements: Select one or more elements in the request or response. This adds a preview for each selected element.

   • The entire payload: Select Body to add the full payload body.

3. To create an attribute from an element, select + Add in the Attribute Preview panel.

4. Save your API message.

Any message elements you create from a response also appear in the Verifications tab of the playground.

Create API test case from API message

To create an API test case, follow these steps:

1. Select an existing API message or create a new one.

2. Select Create API test case.

3. In the menu bar on the left, select Build > Test cases to find your new API test case.

4. Design your test case as needed and save it.

Delete API messages

To delete an API message, go to Build > API messages, select the message to delete, then select Delete API message.