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.

Ready to test an API? You need one or more API messages. Each API message consists of a request and a response module. The request module contains the information necessary 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.

Create an API message

Here's how to create an API message:

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

2. Choose a clear name for your API message.

3. Set up your request:

   • Method - Choose how to send your request.

   • Endpoint - Add the URL for your API. Tosca Cloud currently supports HTTP and HTTPS.

   • Payload - Include the data you want to send.

   • Headers - If needed, add extra information, such as content type or custom fields.

   • Authorization - Enter basic authentication credentials if your service requires it.

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:

API playground

Set up verification

Verifications help you test whether your service works as expected. You can verify message format, content, or response codes. Just set the values you expect and compare them to what the service actually 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 an entry of the newly created verification and edit the following properties:

   • Name - Give your verification a unique name.

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

   • Expression - If you picked JsonPath or XPath, add your expression here.

   • Operator - Choose your comparison method. Possible operators are Equal, NotEqual, Smaller, LessOrEqual, Greater, or GreaterOrEqual.

   • Value - Enter the expected value.

5. Select Save.

This example uses XPath to check a calculation result.

Run a quick test

Want to test your API message right now? Here's how to run a quick one-time test:

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 - See if your verification passed, if you set any.

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 steer 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.

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 will add 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 will also appear in the Verifications tab of the playground.

Delete API messages

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