Legacy Documentation
You're viewing legacy documentation for API Fortress (deployed via an on-premises container). To view documentation for the new SaaS version of API Fortress — now known as Sauce Labs API Testing and Monitoring (with Sauce Connect tunnels) — see API Testing on the Sauce Labs Cloud.

Use the API (For CI/CD & More)

Here is a guide showing you various ways to call the API. This is particularly useful for those that want to use the platform to run tests during continuous deployments, and who are not using our Jenkins plugin. First, you need to create the API Hook by going to the Company Settings page and clicking API Hooks section. To do this you need to be a Manager of the Company. companySetting_generateWebHook Here, click +API Hook you will be prompted to choose a project. Once done, you will have the Hook URL that will give you the ability to query resources from that project. An example is https://mastiff.apifortress.com/app/api/rest/v3/34d8mm70-c03e-267a-9fa1-90b9flsbcea2607 Note: That unique project hook is 34d8mm70-c03e-267a-9fa1-90b9flsbcea2607. This is useful for later. A Quick Table of Contents:

Unauthenticated Endpoints

Test Run

Invoking the execution of a test via the API is a key feature of API Fortress. It allows you to trigger one, or multiple, tests to run. It can also receive input variables to override those in the tests themselves. Finally, you can also send a payload to the platform to be tested against. Optionally, for all the endpoints you can add the following query parameters:
  • sync (boolean): the test will run synchronously and return the result as the response payload.
  • dryrun (boolean): the test will run but no events or metrics will be stored.
  • silent (boolean): no alerts will be triggered by the execution of the test.

Basic: Run a Test By Test ID

How to find a test ID. GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/run Mock Example:
curl -v https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/34d8mm70-c03e-267a-9fa1-90b9flsbcea2607/tests/129d32j9dksdoo23e393/run

Advanced: Run a Test With Additional Information (Variable Override)

If you want to override variables, or include a payload, you have to use: POST https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/run The request body will contain the variable you want to override. Example body
{
  "payload": "{\"id\":\"123\"}",
  "Content-Type": "application/json",
  "params": {
    "server": "staging"
  }
}
  • Params will be accessible as variables inside the test.
  • Payload will be parsed based on the “Content-Type” field and will be accessible via the “payload” variable.
payload AND params are not required at the same time. Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/run \
-H 'content-type: application/json' \
-d '{
"payload": "{\"id\":\"123\"}",
"Content-Type": "application/json",
"params": {"server":"staging"}
}'

Automatch: Run Multiple Tests Based On a URL Pattern

Automatch is a way to simultaneously launch tests inside a project. The tests to run are selected by comparing the URL provided in the payload to the “automatch” configuration pattern in the tests. Just like the advanced run endpoint, you can override both variables and the payload: POST https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/automatch Example body
{
  "payload": "{\"id\":\"123\"}",
  "Content-Type": "application/json",
  "params": {
    "server": "staging"
  },
  "url": "http://www.testme.com"
}
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/automatch \
 -H 'content-type: application/json' \
 -d '{
 "payload": "{\"id\":\"123\"}",
 "Content-Type": "application/json",
 "params": {"server":"staging"}
}'

Basic Tags: Run Tests With Certain Tags

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/tag/tag/run Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/tag/staging/run \
 -d '{
 "payload": "{\"id\":\"123\"}",
 "Content-Type": "application/json",
 "params": {"server":"staging"}
}'

Advanced Tags: Run Tests Tagged With a Certain Word

POST https://mastiff.apifortress.comapp/api/rest/v3/project_hook/tests/tag/tag/run Example body
{
  "payload": "{\"id\":\"123\"}",
  "Content-Type": "application/json",
  "params": {
    "server": "staging"
  }
}
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/tag/staging/run \
 -H 'content-type: application/json' \
 -d '{
 "payload": "{\"id\":\"123\"}",
 "Content-Type": "application/json",
 "params": {"server":"staging"}
}'

Basic By Project: Run all Published Tests of a Specific Project

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/run-all Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/run-all \
 -d '{
 "payload": "{\"id\":\"123\"}",
 "Content-Type": "application/json",
 "params": {"server":"staging"}
}'

Advanced By Project: Run All Published Tests of a Project With Additional Information

POST https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/run-all Example body
{
  "payload": "{\"id\":\"123\"}",
  "Content-Type": "application/json",
  "params": {
    "server": "staging"
  }
}
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/run-all \
 -H 'content-type: application/json' \
 -d '{
 "payload": "{\"id\":\"123\"}",
 "Content-Type": "application/json",
 "params": {"server":"staging"}
}'

Insights (Data & Information)

The API Fortress API also allows you to retrieve metrics and data of your tests.

Events: Shows Information About Test Failures and Successes

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/insights/events Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/insights/events

Events Stream: Show Test Success and Failure Information As An Event Stream

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/insights/events/stream Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/insights/events/stream

Metrics: Provide Details on Performance

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/insights/metrics Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/insights/metrics

Metrics Stream: Provide Details on Performance in an Event Stream

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/insights/metrics/stream Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/insights/metrics/stream

List of Tests in a Project

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests

Details of a Project

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/ Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/

Authenticated endpoints

The following endpoints might contain sensitive information, therefore authentication is required.

Authentication

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/login The user credentials, provided by basic HTTP authentication, need to match the user profile selected during the project hook creation. This endpoint will generate a JWT token which is valid only for the provided project hook. The token is necessary for all the endpoints containing potentially sensitive information, and updating data. The authentication is achieved by sending a valid access token in the request header, in the form Authorization: Bearer access_token Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/login \
 -H 'authorization: Basic ABCD' \
 -H 'content-type: application/json'

Insights (Data & Information)

Provide Details About a Specific Event

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/insights/events/event_id The event_id can be retrieved by performing the events endpoint first. Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/insights/events/5963451d12b87d3379d2f1co \
 -H 'autho: Bearer ABCD' \
 -H 'content-type: application/json'

Tests

Provide the Details About a Specific Test

GET https://mastiff.apifortress.com/api/rest/v3/project_hook/tests/test_id The test_id can be retrieved by calling the test endpoint or, the easiest way, by copying it from the interstitial page: testidIntersitialtestID Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: application/json'

Show the Content of the Unit for the Given Test

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/unit Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/unit \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: application/json'

Show the Content of the Unit for the Given Test as a Downloadable File

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/unit/file Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/unit/file \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: application/json'

Show the Content of the Input-Set for the Given Test

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/input Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/input \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: application/json'

Show the Content of the Input-Set for the Given Test as a Downloadable File

GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/input/file Mock Example:
curl -X GET \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/input/file \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: application/json'

Update Tests

Update the Unit of a Given Test

POST https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/unit/update The unit will be passed as body. Example body:
{
  "text": "<unit xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" name=\"main\" xsi:noNamespaceSchemaLocation=\"http://apifortress.com/app/unit.xsd\"><requirements></requirements><configs></configs><sequence name=\"main\"><assert-exists expression=\"payload\"/></sequence></unit>"
}
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/unit/update \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: application/json' \
 -d '{
 "text": "<unit xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" name=\"main\" xsi:noNamespaceSchemaLocation=\"http://apifortress.com/app/unit.xsd\"><requirements></requirements><configs></configs><sequence name=\"main\"><assert-exists expression=\"payload\"/></sequence></unit>"
}'

Update the Unit of a Given Test by Accepting It As a Raw POST Body

POST https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/unit/update/file The unit will be passed as body. Example body
<unit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="main" xsi:noNamespaceSchemaLocation="http://apifortress.com/app/unit.xsd">
    <requirements></requirements>
    <configs></configs>
    <sequence name="main">
        <get url="${protocol}${domain}${endpoint}" params="['id':id]" var="payload" mode="json"></get>
        <assert-equals expression="payload.status" value="200" comment="status is equal to 200, if not stop the test" stoponfail="true"/>
    </sequence>
</unit>
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/unit/update/file \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: text/xml' \
 -d '<unit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="main" xsi:noNamespaceSchemaLocation="http://apifortress.com/app/unit.xsd">
 <requirements></requirements>
 <configs></configs>
 <sequence name="main">
 <get url="${protocol}${domain}${endpoint}" params="['\''id'\'':id]" var="payload" mode="json"></get>
 <assert-equals expression="payload.status" value="200" comment="status is equal to 200, if not stop the test" stoponfail="true"/>
 </sequence>
</unit>'

Update the Input-Set of the Given Test

POST https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/input/update The input will be passed as body. Example body
{
  "text": "<sets xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" name=\"main\" xsi:noNamespaceSchemaLocation=\"http://mastiff.apifortress.com/app/input.xsd\"><global><param name=\"country\">US</param></global><set name=\"search 1\"><param name=\"q\">music</param></set></sets>"
}
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/input/update \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: application/json' \
 -d '{
 "text": "<sets xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" name=\"main\" xsi:noNamespaceSchemaLocation=\"http://mastiff.apifortress.com/app/input.xsd\"><global><param name=\"country\">US</param></global><set name=\"search 1\"><param name=\"q\">music</param></set></sets>"
}'

Update the Input of a Given Test By Accepting It As a Raw Post Body

POST https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/input/update/file The input will be passed as body. Example body
<sets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="main" xsi:noNamespaceSchemaLocation="http://mastiff.apifortress.com/app/input.xsd">
    <global>
        <param name="protocol">https://</param>
        <param name="domain">mastiff.apifortress.com</param>
        <param name="endpoint">/app/api/examples/retail/product</param>
    </global>
    <set name="ID 1">
        <param name="id">511</param>
    </set>
</sets>
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/6de267cd-df01-4782-8046-3seee6f4c093782/tests/35082607e4b0mm613lm82e8f/input/update/file \
 -H 'authorization: Bearer ABCD' \
 -H 'content-type: text/xml' \
 -d '<sets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="main" xsi:noNamespaceSchemaLocation="http://mastiff.apifortress.com/app/input.xsd">
 <global>
 <param name="protocol">https://</param>
 <param name="domain">mastiff.apifortress.com</param>
 <param name="endpoint">/app/api/examples/retail/product</param>
 </global>
 <set name="ID 1">
 <param name="id">511</param>
 </set>
</sets>'

Creating Tests Outside of API Fortress

Validators

When developing outside the API Fortress Composer, you will want to be sure the syntax of your units and input-sets are correct. For this work there are two different endpoints. One for the input-set, and one for the unit.

Validate the Unit

POST https://mastiff.apifortress.com/app/api/rest/v3/validators/unit The unit will be passed as body. Example Body
{
  "text": "<unit xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" name=\"main\" xsi:noNamespaceSchemaLocation=\"http://apifortress.com/app/unit.xsd\"><requirements></requirements><configs></configs><sequence name=\"main\"><assert-exists expression=\"payload\"/></sequence></unit>"
}
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/validators/unit \
 -H 'content-type: application/json' \
 -d '{
 "text": "<unit xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" name=\"main\" xsi:noNamespaceSchemaLocation=\"http://apifortress.com/app/unit.xsd\"><requirements></requirements><configs></configs><sequence name=\"main\"><assert-exists expression=\"payload\"/></sequence></unit>"
}'

Validate the Input-Set

POST https://mastiff.apifortress.com/app/api/rest/v3/validators/input The input-set will be passed as body Example Body:
{
  "text": "<sets xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" name=\"main\" xsi:noNamespaceSchemaLocation=\"http://mastiff.apifortress.com/app/input.xsd\"><global><param name=\"country\">US</param></global><set name=\"search 1\"><param name=\"q\">music</param></set></sets>"
}
Mock Example:
curl -X POST \
https://private-e9aac-apifortressv3.apiary-mock.com/app/api/rest/v3/validators/input \
 -H 'content-type: application/json' \
 -d '{
 "text": "<sets xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" name=\"main\" xsi:noNamespaceSchemaLocation=\"http://mastiff.apifortress.com/app/input.xsd\"><global><param name=\"country\">US</param></global><set name=\"search 1\"><param name=\"q\">music</param></set></sets>"
}'

Converting to JUnit Format

Converting to JUnit format (for Jenkins/QTest/etc.) is done by adding the following query parameters to a request:
?sync=true&format=junit
The completed request would be as follows: GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/run-all?sync=true&format=junit This can also be done for an individual test: GET https://mastiff.apifortress.com/app/api/rest/v3/project_hook/tests/test_id/run?sync=true&format=junit   Keywords: cicd, jenkins, bamboo, microsoft tfs, team foundation server, gitlab ci/cd, travisci