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

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

 

API Fortress – Using the v2 API (deprecated)

Preamble

API Fortress exposes most of its functionalities via an API to allow automation and scripting. For example, you can trigger a test to automatically execute during a Jenkins deployment. Use of the API is available to all paid accounts. Please email info@apifortress.com to get setup.

The scope of this document is providing an overview of the endpoints.

Two versions of it are currently coexisting:

  • default – where most functionalities currently reside on.
  • v2 – which implements the new “test API.”

Authentication

The authentication flow for the API is fairly simple.
1. Using the company settings dashboard, generate a key and secret pair.

add key

2. While making a request to the API, create a token by applying the following algorithm:

md5(key+secret+epoch)

where “epoch” is the Unix time.

3. Add the following headers to the request:

X-Key : <your_api_key_here>
X-Token : <your_generated_token_here>

Remember that tokens are very short lived and should be generated for each request.

default : /api/rest/company

Actions related to the company profile.

  • GET /details : provide details for the current company

Default : /api/rest/event

Provides access to the event objects.

  • GET /list/{projectId} : lists out all the events of the last week for the given project.
  • GET /details/{eventId} : provide the details of the event with the given id.

Default : /api/rest/monitor

Provides access to the metrics objects.

  • GET /list/{projectId} : lists out all the metrics events of the last week for the given project.

Default : /api/rest/schedule

Provides access to the scheduler data.

  • GET /byTest/{testId} : lists all the scheduler settings for the given test.
  • GET /byProject/{projectId} : lists all the scheduler settings for the given project.

V2 : /api/rest/v2/test

Controls a number of test interactions.

  • GET /list/{projectId} : lists all the tests for the given project.
  • GET /details/{testId} : provides details for the given test.
  • GET /statuses/{projectId} : tells whether the latest execution of each test for the given project succeeded or failed.
  • POST /run/{testId} : runs a test, possibly against a provided payload. The body of the post depends on the options set in query params:
    downloader optional if the test has to retrieve certain resources then you might want to choose which downloader is going to be used. If not set, the default will be used.
    silent optional if set to “true” the test will not trigger any alert.
    dryrun optional if set to “true” the result of the test will not be saved.
    sync optional if set to “true” the test will run a foreground process and will return the result of the test.
    nosets optional if set to “true” the test will ignore the input sets and run the unit only once (typical when the payload is provided).
    mode required can either be “payload” or “serializer.”
    Payload Mode

    When set to “payload” mode the required POST body will look like this:

{
  "Content-Type": "application/json",
  "payload": "{\"success\":true,\"data\":[\"one\",\"two\",\"three\"]}"
  "params": { "server": "15a" }
}

Content-Type: is the content type of the “payload” being forwarded.
payload: is the body of the payload to be tested. In the test, it will be referenced as the variable “payload.”
params: extra parameters you might want to make available to the environment. In the test they will be available as variables.

Note: if you want to run a test without payload forwarding you can send an empty object.

Serializer Mode

The serializer mode allows an agent to send full “request and response” serializations to the API Fortress engine. See [Serializer] for more details.

  • POST /runAutomatch/{projectId} : runs multiple tests inside a project, based on the automatch strategy. See [Automatch] for more details.
    The options are pretty much the same for the previous endpoint:
downloader optional if the test has to retrieve certain resources then you might want to choose which downloader is going to be used. If not set, the default will be used.
silent optional if set to “true” the test will not trigger any alert.
dryrun optional if set to “true” the result of the test will not be saved.
nosets optional if set to “true” the test will ignore the input sets and run the unit only once (typical when the payload is provided).
mode required can either be “payload” or “serializer.”