Using the API (For Continuous Deployment & 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>"
}'

 

 

Using the Jenkins Plugin

The API Fortress Jenkins Plugin allows you to run tests during automated builds. The tests that fail may, or may not, cause a build failure based on your settings.

Install the Jenkins plugin

From the Jenkins Update Center, search and install the API Fortress plugin.

jenkins1A Jenkins restart may be required. You will be prompted accordingly.

Configure a build step

Add the API Fortress build step where it best suits your needs.

jenkins2

Modes

There are 4 testing modes available. “Run single test” will run a single test, while the others will run suites of tests.

Run Single Test

You can run a single test by providing a test ID. Test IDs can be found in test interstitial pages.

See where to retrieve the test IDs later in this document.

Run Automatch

You can run our “automatch” mode by providing a URL representing a certain endpoint. You can configure automatch patterns in the “Automatch” section of each test. Read more about automatch here .

Run by Tag

Choosing “by tag” will run multiple tests marked with a certain tag. Tags can be added and edited in the test details.

Run Project

By running a full project, you will be running all tests contained in the project.

Hook URL

The hook URL is an API endpoint that references a specific project within an API Fortress environment.

See the Hook URLs section to create one.

Options

The following options can apply to any mode.

Blocking

The plugin can silently run (blocking = false), which lets the build continue with a success and inform you if the test failed using the various methods available. Or it can actively determine the build success (blocking=true), so that the build will wait for the tests result and stop the build if the tests fail.

Dry-run

If checked, no events will be stored within API Fortress. To be used in conjunction with “blocking.”

Silent

If checked, no alerts will be sent if the tests fail.

Parameters Override

You can override up to 3 parameters in the test scope. These variables will appear within the test scope just like any other variable. Useful if you are looking to override the domain of the service being tested (ie. staging vs production).

Hook URLs

Hook URLs are API endpoints representing one of your projects. These endpoints have unique paths, and do not require authentication for most non-disclosing operations.

To create a Hook URL:

  1. Access your API Fortress dashboard.
  2. Enter the company configuration screen (gear icon in the top right).
  3. Choose API Hooks on the side menu.
  4. Create a new Hook by choosing the user (necessary for advanced functions) and the project.
  5. A unique URL will be generated. That is the URL to be used in your build step configuration.

Test IDs and Project ID

To retrieve a specific test ID from the API Fortress dashboard:

  1. Access the tests list for the project you intend to use.
  2. Edit one of tests and access the interstitial page.
  3. Click on “show/hide test information.”
    jenkins4
  4. The test ID and the Project ID are shown here.

Input set and global variables

In the test creation process, the definition of global and local variables allows you to parametrize the test to allow more flexibility.

The global variables are meant to be the ones that are common for the whole test (i.e. api key, domain etc). For adding a global variable click on the +Add Global Param in the Data Set panel and fill the name and value.

variable

globalThe variable will be present in the test scope, and will be constant during the test exeuction.

The input set, instead, is a group of input variables representing a scenario (i.e product id). To add in input set, click the + button in the Input Set section and add a name for the set. Then click + Add Param and add the variable name and value.

inputSet

The unit will be executed once for each input set you have defined. At each iteration, one input set will enter the scope.

If you define a variable both in the global section and the input set, the value used in the test will be the one defined in the input set.

The variables can be defined also in the Vault (for more info see here) and in the Schedule (for more info see here).

The priority order is:

  • if the same variable is defined in the Vault and in the composer (no matter if it is a global variable or an input set), the one defined in the composer will be used.
  • if the same variable is defined in the composer both as global and input set, the value of the input set will be used
  • if the same variable is defined in the Vault (or in the composer) and in the scheduler, the variable defined in the scheduler will be used for the tests.

Proof of Concept Time – Get Excited!

Welcome to your API Fortress trial!

You should have received an email with your login credentials from the platform. If you haven’t please email API Fortress.

The links below are resources that will easily get you started with standing up your APIs. If additional resources are required please do not hesitate to reach out. Our lines of communications are always open to support you throughout this process.

Keys to a Successful Evaluation

Phase 1:

Phase 2:

Phase 3:

More Docs

API Fortress Documentation
Quick Start Guide – Create a Test
Creating a Multistep Test (Integration Testing)
Videos
More Videos

Example public APIs to play with:
Retail API
Uber API

Please let us know if there is anything else we can do to help with the evaluation process.

Build from Postman Collection

API Fortress can now generate a test from a Postman collection!

The first step is exporting your collection from within Postman.

collection

Next to your Collection name click the ellipsis (three dots) … then click Export and choose ‘Collection v2.’

export exportCollectionV2

Once done, go to API Fortress and create a New Test.

newTest

On the interstitial page, click Build from Spec.

buildFromSpec

In the following page, choose Postman Collection from the dropdown menu, and upload the collection file we exported. Click Save.

specFile

For a new test, choose From Scratch and then click the check. If you are updating a test then you would use the Merge option.

buildoptions

This imports the API call to the composer. Now we can use this to call the payload and build a test automatically!

testcreated

The easiest way to create a test is using our Magic tool. To do so you need to import the call into the console. First, select the call in the composer, which will highlight it, then click the Import button (shown highlighted below).

importFromComposer

This will open the HTTP console at the bottom and load the call.

importToConsole

When the call is in the console, click the Send button in the top right and you will see the response.

response

At this point, the Magic tool can do the test for you. Click the magic wand icon next to the send icon at the top right of the console, that will launch the Magic tool. Click Continue a few times and voila, a complete API test generated without having to write any code.

magic

You can review the test and add some more logic. This is just a simple version of the test!

 

 

 

 

Vault – Stored Variables & Code Snippets

The vault allows you to store variables and fragments of tests (code snippets) that can be used across an entire project.

The link to access the Vault is in the top menu.

header

The first column shows all the projects of company. Code snippets and variables are available on a per project basis. Note: They are not available across projects. We did this for a specific reason based on customer feedback.

vault

snippet&variables

In the snippet section, you will find all the snippets you have created using the composer (see here for more details).

snippet

A good example for the snippets feature is an authentication flow: you don’t need to write all the steps in every test, you just need to call the snippet that contains the authentication fragment. Another good example is integration tests, where you can reuse various tests to create one larger flow.

In the variable section, you can define variables which will be part of the scope of the tests.

variable

If a variable with the same name is defined within the test, it will override the one defined in the Vault.

Defining a variable in the vault is helpful when you need to use the same variable in different tests, in this way you don’t need to write it every time. You can also save a password as variable.

Here is a quick example on how the Vault can be used in a test.

The Authentication Snippet

First, create a new test. Go to the test list, click +New Test, enter the test name and click Compose. Once the composer appears, we need to enter the call. For this example, we will add a GET that logs in using a Basic authentication:

login

Consider a scenario where this login will be required for all the endpoints we have to test. It makes sense for this call to be stored in the Vault.

Select the GET, open the Vault panel and click the + button. Enter a name and description.

loginSnippet

Now you can proceed creating the test. Once done we need to create the other tests for our API. Once again, click +New Test. Once you are in the composer, you can open the Vault panel and select the snippet we saved in the previous step.

newTestSnippet

 

To invoke the login call into the new test, we just need to click the down arrow button near the snippet, and it will be added into the test.

invokeSnippet

 

Now we can call the endpoint we want to test. Let us use the search endpoint, where we pass the ‘id’ variable as a parameter, and the token is retrieved from the login call:

call_search

Now consider the case where we want to use the same ‘id’ in multiple tests, so we do not set the id as either a global param nor as an input set. We add it in the vault instead. Save the test and exit from the composer. Click on Vault in the header and add the variable ‘id’ here:

saveVar

Once done, go back to the test and check that the variable is available in the Vault panel:

varInVault

Now if you launch the test you can see that the ‘id’ will be replaced with the value you have set in the Vault.

 

 

Generate a Status Page

This may be the easiest doc of them all. Generating a status page is as simple as clicking the Gear icon in the top right, and going to the Status Pages section.

There are two options here. Big Screens automatically refreshes itself, so it works really well for TVs or monitors in a DevOps office for example. This view is only viewable by users registered to your company. Shareable generated a link that gives a snapshot of the API’s health at the moment the page is loaded. It can be shared publicly without needing an account to API Fortress.

status page
Arrows to the Gear icon and Status Pages section of the Settings page.

Build from Mashery

You can now generate a draft an API test from the I/O Docs in your Mashery account!

On the test interstitial page there is a “Build from Mashery” button. Click it, enter the Username, Password and Area ID from your Mashery account.

Choose the I/O Doc you want to use, then choose the action you want to create a test for, and the click the lightning bolt.

You can also have API Fortress generate some assertions for you by using the ‘magic’ tool. From the composer, click the “import the request into the console” button from the top navigation. The HTTP console will open. From there insert the required values and make the call. Finally, click the Magic Wand icon (skip the global/input set generation step) and that’s it. An API test is created for you!

From here you can add more intelligence to the test. Maybe make it an integration test with more calls, or add an IF statement. A lot of options are at your disposal.

ezgif.com-video-to-gif

On-Premises Deployment – Using Docker

Introduction

This manual will describe a normal deployment procedure for API Fortress on-premises, using a Docker container. It is important to remember that the goal of this guide is to be as thorough as possible. It may seem long but the process is fairly straightforward.

Also, don’t fret as we can provide as much help and guidance as you need. We are just a video conference away!

You have been provided with apifortress_starter.zip, which contains the following files:
/create_network.sh
/
core/docker-compose.yml
/
core/tomcat_conf/conf/
/core/start_all.sh
/
downloader/docker-compose.yml
/data/connectors.tgz
/data/help.tgz
/data/import_help.sh
/data/import_connectors.sh

1. Copy the Provided Script Files

Copy the provided core and downloader directories to the server and then type cd core/.

2. Configure the Core Services

Before anything else, let’s configure each service and prepare the environment.
Most configuration keys are stored within the core/docker-compose.yml file.

PostgreSQL
The only special configuration will be the storage on the host machine.
Create a directory that will host PostgreSQL data in the host machine, and edit configuration file with that location. Replace the “/data/postgres” with your details.

    volumes:
   - /data/postgres:/var/lib/postgresql/data

MongoDB
As with PostgreSQL, you are required to provide a storage location and edit the volumes key accordingly. Replace the “/data/mongodb” with your location.

  volumes:
  - /data/mongodb:/data/db

API Fortress
There are a lot of configuration keys here. None of them should be left empty (a fake value is fine if you’re not using a certain feature). See the API Fortress Configuration Guide below for an explanation of each key.

The essential keys for bootstrap (with dummy values) are:

Admin User Creation
adminEmail: patrick@company.com
adminFullName: Patrick Poulin

Company Creation
defaultCompanyName: Your Company

Base URL that will respond to HTTP requests
grailsServerURL: http://yourcompany.com/app

API Fortress Mailer
Refer below.

API Fortress Downloader
To be configured after the dashboard bootstrap. Refer below.

3. Install Docker

Install Docker on a supported Linux distribution following the official instructions:
https://docs.docker.com/engine/installation/
The API Fortress stack runs successfully on Docker 1.12.

4. Install Docker Compose

Docker Compose is a utility that simplifies the deployment and management of complete stacks. Follow the official instructions for installation:
https://docs.docker.com/compose/install/

5. Provide API Fortress your DockerHub username

For API Fortress to grant you access to the API Fortress registries, your DockerHub username is required.  If you don’t have a DockerHub account, create one at https://hub.docker.com/

6. Login

Type sudo docker login and input your DockerHub credentials.

7. Create the API Fortress network

The default API Fortress subnet is 172.18.0.0/16. Make sure the default subnet is not in use. If it is then edit it in the create_network.sh script. Issue sudo ./create_network.sh  to create a virtual subnet for API Fortress.

8. Launch the Services

Before you launch any service, we strongly recommend you to run a: docker-compose pull  from the “core” and “downloader” directories to download all packages and preemptively verify any possible connection issue.

To launch all core services, just run the start_all.sh script. It will take some time, but it will ensure every dependency is up and running before launching API Fortress.

9. Verify the Deployment

At the end of the process, the API Fortress dashboard should be up and running in the host server on port 80. You can also check for errors in the logs by issuing the: sudo docker-compose logs command.

The admin user login details are as follows:

  • username: the email address provided in the docker-compose configuration, in the adminEmail field;
  • password: ‘foobar’, change it as soon as you log in.

10. Configure and Run the Downloader

The API Fortress downloader is the agent that retrieves the resources to be tested. Downloaders can be installed in various locations, so factors such as latency and download time can be measured by remote consumers.

In this configuration path, we are deploying a downloader in the same server as API Fortress, and it will serve as the default downloader.

1. Edit the downloader/docker-compose.yml file and take note of the value of the ipv4_address configuration key.

2. Login to API Fortress with the admin user, access the API Fortress admin panel by clicking the “user” icon in the top right, then click Admin Panel.

login

3. Choose “Downloaders” from the list of actions and click on the “Add Downloader” button.

4. Fill the fields:
Name: Write a recognizable name.
Location: A representation of where the downloader is. ie. Chicago
Latitude / Longitude: The geographical position of the downloader.
Last Resort: Check this to make it the default downloader used.
URL: The address of the downloader, followed by port (default 8819) and path /api. In our example, the ipv4_address and our downloader address would result in https://172.18.1.1:8819/api
API Key, API Secret: Write these two values down for use later.

5. Edit the  downloader/docker-compose.yml file and enter the API Key and API Secret.

6. Go to the downloader/ directory and issue the sudo docker-compose up -d command.

API Fortress Configuration Guide

A description of each configuration field you may need to alter.

API Fortress Dashboard

Bootstrap:
 – adminEmail: The admin user email address, also used as login.
 – adminFullName: The admin’s full name.
 – defaultCompanyName: The company name.

System:
 – grailsServerURL: the url the server will respond to
 – dbHost: MongoDB host
 – psqlhost: PostgreSQL host
 – rabbitHost: RabbitMQ host

Note: in case you’re considering using an external PostgreSQL provider, the psqlUsername and psqlPassword parameters are also available. The database name is fixed and it’s apipulse.

Email:
 – apifortressMailUseSES: set to ‘true’ if you will use Amazon SES to send emails. When set to ‘false’, SMTP is used instead.
 – apifortressMailFrom: the email address that will be used to dispatch administrative emails.
 – apifortressMailSmtpHost: SMTP host to dispatch administrative emails.
 – apifortressMailSmtpUsername: SMTP username.
 – apifortressMailSmtpPassword: SMTP password.
 – apifortressMailSmtpPort: SMTP port.
 – amazonkey: Amazon key, if you’re using Amazon SES to send emails.
 – amazonsecret: Amazon secret, if you’re using Amazon SES to send emails.
 – apiaryClientId: client ID if you’re using Apiary services.
 – apiarySecret: secret, if you’re using Apiary services.
 – license: the license string.

API Fortress Mailer
 – twilioSid: SID, if you’re sending SMSes via Twilio.
 – twilioToken: token, if you’re sending SMSes via Twilio.
 – smsFrom: the phone number of the SMS sender, if you’re sending SMSes via Twilio.
 – mailFrom: the email address that will be sending notification emails.
 – mailUseSES: ‘true’ if you’re sending emails via Amazon SES. False if you’re using SMTP.
 – amazonKey: the Amazon key, if you’re sending emails via Amazon SES.
 – amazonSecret: the Amazon secret, if you’re sending emails via Amazon SES.
 – mailSmtpHost: the SMTP host.
 – mailSmtpPort: the SMTP port.
 – mailSmtpUsername: the SMTP username.
 – mailSmtpPassword: the SMTP password.
 – apifortressServerURL: the url the server will respond to.

API Fortress Downloader
 – apikey: the API key, as shown in the admin panel.
 – secret: the API secret, as shown in the admin panel.
 – port: the HTTP port the server will be listening to, in HTTP mode.
 – rabbitHost: the RabbitMQ host, when running in active mode.
 – rabbitPort: the RabbitMQ port, when running in active mode.
 – rabbitSsl: ‘true’ if RabbitMQ will need to communicate over SSL when running in active mode.
 – rabbitUsername: the RabbitMQ username when running in active mode.
 – rabbitPassword: the RabbitMQ password when running in active mode.
 – use_rabbit: ‘true’ to run in active mode.
 – use_http: ‘true’ to use the internal HTTP server (passive mode).
 – use_ssl: ‘true’ if the internal HTTP server has to run over SSL.

The network configuration is also important as the IP address may be used for internal communication.

networks.apifortress.ipv4_address: the reserved IP address in the API Fortress subnet.

Appendix: Importing help tools and connectors

The API Fortress database comes free from data, but the provided package gives you the option to import the help tools and the connectors. These operations are meant to be run once the API Fortress stack is fully functional.

Import Help From the /data directory, run the import_help.sh script.
Import Connectors From the /data directory, run the import_connectors.sh script.

Appendix: Tweaking Tomcat Configuration

If you need to tweak the Tomcat configuration, you will need to mount the Tomcat conf/ directory in your system.
1. Change the configuration files you need to edit in the core/tomcat_conf/conf directory
2. Mount the directory by uncommenting the following lines in the core/docker-compose.yml file:

# volumes:
# - ./tomcat_conf/conf:/usr/local/tomcat/conf

Dashboard over SSL

To have Tomcat running over SSL:
1. Copy your JKS keystore containing your certificate in the core/tomcat_conf/conf directory
2. 
Edit the core/tomcat_conf/conf/server.xml file and uncomment the block:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11Protocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" />

3. Edit the block by adding the following attributes:

keystoreFile="/usr/local/tomcat/conf/keystore.jks"
keystorePass="thePasswordHere"

4. Mount the directory by uncommenting the following lines in the core/docker-compose.yml file:

# volumes:
# - ./tomcat_conf/conf:/usr/local/tomcat/conf

5. In the core/docker-compose.yml file, change the port declaration to:
ports:

- 443:8443/tcp

Dealing with Authorizations (simple, oAuth, etc)

Introduction

API Fortress would not be very useful if it couldn’t handle virtually every type of authorization. Thankfully, it can. Below we provide some guides on simple ways to work with the most common authorization methods. If it requires usage of a long lasting token, see that information here.

Simple Authorization

Here is how to handle a simple username and password authorization. We are working on a wizard to make this more simple, so expect to see that soon! For now, here are the steps:

  1. Click on Tools, then Gadgets in the top bar.
    Screen Shot 2017-01-20 at 11.06.53 AM
  2. Choose base64 encode, then input your credentials in this manner “username:password” and then click base-64-encode.
    Screen Shot 2017-01-20 at 11.11.10 AM
  3. In the composer add a GET component. Enter your information.
    Screen Shot 2017-01-20 at 11.12.55 AM
  4. Then click on “+Add Header” at the bottom header and enter Name=Authorization value=Basic <thecodeyouhavegenerated>. For this example we entered “dXNlcm5hbWU6cGFzc3dvcmQ=” as the value.
    Screen Shot 2017-01-20 at 11.23.46 AM
  5. That’s it! The call should work now. If not feel free to send us a message at support@apifortress.com!