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!

Using Long Lasting Tokens

Introduction
It is common for an authentication system to generate long lasting tokens to perform multiple requests. In API Fortress there are many paths of authenticating that can be taken, but sometimes users prefer the token reuse strategy.

Goal
In this example we are showing you how to allow a test to store a token for further executions, and refresh it when it’s time. Each test will need to contain this logic, and each token will be bound to the test itself.

Here’s the complete test. Have a quick look at it before proceeding to the steps:

  1. Prepare the input set by adding the basePath, loginPath, and dataPath. Most importantly, add an empty variable for token and expires. These items will be updated by the test.
    1
  2. Add an IF component with this logic:
    !expires || D.nowMillis()>expires.toLong()

    3

  3. Within the IF branch, make the login call. Shown here is a call to the login URL. We are storing the retrieved information in the variable named “loginPayload.”
    4
  4. Within the IF branch, set the value to token and expires. Note that in the value we’re saying: take the current time and add one hour
    D.plusHours( D.nowMillis(), 1 )

    56

  5. Within the if branch, update the input set. This is a unique feature of API Fortress. By performing this operation, you’re having the test modify itself for the next use by updating the token and the expires variables. By doing so, the token will be available for all tests executions that will happen within an hour, and therefore no login calls will be made.
    7 8
  6. After the IF branch, perform the main call. We can reference the previously updated token.
    call

Effects
When running outside the workbench, two subsequent test executions will look like this:
910

Code View
The whole operation might seem a bit annoying to replicate in every test, but the code view and some copy and paste can ease the pain.

Note:
Keep in mind this is just an example, and the calls are meant to be very simple The following is the code version of the IF branch containing the authentication logic.

<if expression="!expires || D.nowMillis()&gt;expires.toLong()">
  <comment>
    <![CDATA[Authentication has to be performed due to expired token]]>
  </comment>
  <post url="${basePath}${loginPath}" params="[:]" var="loginPayload" mode="json">
    <postParam name="username" value="test"/>
    <postParam name="password" value="test"/>
  </post>
  <set var="token" value="${loginPayload.token}" lang="java"/>
  <set var="expires" value="${D.plusHours(D.nowMillis(),1)}"/>
  <update-input var="token"/>
  <update-input var="expires"/>
</if>

More Notes
Updating input variables won’t work when launching a test from within the composer, so the login call will run every time when developing a test. Run the test from outside the composer or schedule the test to see it in action.

Language Appendix
Negation: the exclamation mark (!) prior to an expression is used as a negation and it means: when it’s false, when it’s empty, when it does not exist.
In our example: !expires means when expires is empty.
Logic Or: the classic double pipe sign ( || ). Rarely used in API Fortress except in IF conditions.
toLong(): converts a string to a long number.
D.<action>() an API Fortress language extension that provides date and time manipulation functionalities. Please refer to http://apifortress.com/doc/expression-language-extensions/ for further details.

Build from Apiary

Introduction
If you have the right level Apiary account, you can generate a test from your Apiary docs. It’s as simple as a few clicks.

Directions
This GIF pretty much explains it, but from the test composer interstitial page, there is a Build from Apiary button. Click it, login to your Apiary account, and choose which Blueprint to create a test from. Simple, right?

Don’t forget that this is a test draft. Add more logic to it for a really awesome test, maybe add more calls to it as well to create a proper integration test.
build-from-apiary

Local Downloader Setup

1. What it Does

The API Fortress Remote Download Agent sits inside of your infrastructure to allow the platform to test systems that are not exposed externally.

It will listen to an HTTPS port for jobs requested by an API Fortress engine. The agent will perform an HTTP(S) request to an endpoint as described in the job, and once completed will serialize the data back to the engine, adding contextual information such as the metrics.

No data is retained in the agent memory after job completion. The agent will use the DNS settings provided by the machine it’s installed on.

2. General Requirements

    • Software: Java JRE 1.8 or greater
    • Network: the agent should be reachable by the designated API Fortress engine(s)
    • Network: the default inbound port is 8819

3. Cloud Requirements

If the agent is meant to be contacted by the API Fortress cloud, the connection will happen from the following sources:

  • dashboard-aws01-1.apifortress.com – 52.0.5.117
  • dashboard-aws01-2.apifortress.com – 52.2.216.188

4. Installation

Unzip the provided package in a location of your choice.

The package should contain the following files:

  • RemoteDownloadAgent-complete.jar : the agent
  • config.properties : the configuration file
  • LICENSE.md :  the license file
  • VERSION.md : the version file
  • bin/start.sh :  the start script for *NIX systems
  • bin/shutdown.sh : the stop script for *NIX systems
  • bin/java_opts.sh : java related settings for *NIX systems
  • bin/start.bat : the start script for Windows
  • bin/java_opts.bat : java related settings for Windows

5. Configuration

We will preconfigure the config.properties based on your needs.

Here the main items:

serviceName: a human readable identifier of the downloader.
apikey: unique to every downloader. Used by the API Fortress engine to authenticate.
secret: used by the API Fortress engine to authenticate.
use_http (true): enables the HTTP server.
use_ssl (true): enables the SSL encryption for the HTTP server.

6. Running the Agent – *NIX

Run the bin/start.sh script to start the agent which will run in the background.

Run the bin/shutdown.sh script to stop the service.

7. Running the Agent – Windows

Run the bin/start.bat script to start the agent which will run in foreground.

8. Tuning

Even though the agent does not require relevant system resources, it is a good practice to allow the agent to use as much memory as available. By editing the java_opts script (.bat or .sh, depending on the platform) you can tweak the heap memory settings.

Note: Remember that heap memory is not the only type of memory Java uses. Raising the heap to the system limits is not advised, and it will not work. If you are not familiar with these settings, the default will likely meet your requirements.

Connectors (Notification / Integrations)

Introduction
Connectors are the way API Fortress integrates with other services to send data or notifications to them.

There are two types of connectors:

  • Failures Only: this kind of connector will send an event only when a test failure happens. This is typical for stateless services, like Slack
  • Send All: will send all events, including successes, and this is very handy when the service will need to log everything or alter a state

Currently Available
We are constantly adding new integrations and connectors. Currently we have:

  • Slack
  • BigPanda
  • DataDog
  • HipChat
  • StatusPage.io
  • Cisco Spark (soon)
  • Twilio (soon)

Setup
Connectors are part of the Alert Groups subsystem. They can only be set up by users with the “manager” role, and can be accessed by doing the following steps:

  1. Access the company settings page, by clicking the gear top right.
  2. Select “Alert groups” on the side menu.
  3. Create a new group (if needed).
  4. connectorsClick on the connectors icon.
  5. Add a new Connector.
  6. Choose a service from the list.
  7. Fill the required information to make it work.

Once the Alert Group is set, you can assign it to a project by:

  1. Go back to the main dashboard.
  2. Edit a project.
  3. Select your Alert Group in the “Alert distribution group” field.
  4. Save the project.