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.

The apifortress_starter.zip file you’ve been provided contains the following files:

certs/apifortress.crt
core/docker-compose.yml
core/tomcat_conf/conf/
core/create_network.sh
downloader/docker-compose.yml

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 the first part (before the : ) in the configuration, accordingly:

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

MongoDB
As with PostgreSQL, you are required to provide a storage location and edit the volumes key accordingly:

  volumes:
  - /var/tmpmongo:/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: solomon_pi@gmail.com
adminFullName: Solomon Pi

Company creation
defaultCompanyName: The PI

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

API Fortress Mailer
Refer to the API Fortress Configuration Guide below.

API Fortress Downloader
To be configured after the dashboard bootstrap.
Refer to the API Fortress Configuration Guide 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. Install the API Fortress Registry Certificate

To access the API Fortress registry you will need to install the provided certificate. To do so, copy it to the following locations:
/etc/docker/certs.d/utils.apifortress.com:5000/
/usr/local/share/ca-certificates/
Then invoke sudo update-ca-certificates

Additionally, on RedHat copy the certificate to:
/etc/pki/ca-trust/source/anchors/
and invoke update-ca-trust

6. Login

Enter sudo docker login utils.apifortress.com:5000 and input the username and password that have been provided to you.

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

While all services can be launched with one single command, it is possible that slow servers might not be able to launch required services before the consuming service. For this reason we recommend to launch the services individually. The first time the commands are issued, Docker will download the images and then run them. From within the core/ directory, issue the following commands:

PostgreSQL
sudo docker-compose up -d apifortress-postgres

MongoDB
sudo docker-compose up -d apifortress-mongo

RabbitMQ
sudo docker-compose up -d apifortress-rabbit

API Fortress Dashboard
sudo docker-compose up -d apifortress

API Fortress Mailer
sudo docker-compose up -d apifortress-mailer

API Fortress Scheduler
sudo docker-compose up -d apifortress-scheduler

API Fortress Connector
sudo docker-compose up -d apifortress-connector

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 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: give the downloader a recognizable name
Location: a textual representation of where the downloader is. Ie. San Diego
Latitude / Longitude: express the geographical position of the downloader
Last resort: check it if this is your first downloader. It will be chosen automatically when you don’t make a explicit downloader selection.
URL: the address of the downloader, followed by port (default 8819) and path /api. In this scenario, the ipv4_address we previously noted down is our downloader address. Ie. http://172.18.1.1:8819/api
API Key, API Secret: take note of these two values and save.

5. Edit the  downloader/docker-compose.yml file and fill the API Key and API Secret keys with the retrieved values.

6. Run the downloader by issuing the sudo docker-compose up -d command from the downloader/ directory.

Note: as a default, for testing purposes, the downloader will run over HTTP. When running outside a protected channel, consider making it run over HTTPS. In the docker-compose.yml of the downloader, turn on HTTPS by changing the ‘use_ssl’ attribute to true, and make sure that the downloader url in the admin panel starts with https://.

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 full name
 – defaultCompanyName: The company name

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

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