Tutorial 6: Using the CLI and the Hoverfly Cloud API

In this walkthrough you will use the Hoverfly Cloud command line interface, to start a service from the command line. You will then use the Hoverfly Cloud API to modify the behavior of the service.

hcc is a multi-purpose command line interface for Hoverfly Cloud. It provides a convenient way to manage your Hoverfly Cloud virtual services and automate their management. Either for ad-hoc actions via the command line or integrated into scripts that are used by Continuous Integration and DevOps tools such as Jenkins.
You can also capture traffic within your network and publish the simulation to your account with hcc. You can read more about that here.
The Hoverfly Cloud API provides full control over your services, simulations and scenarios, as well as giving you access to the journal, service statistics and behaviors.

Part 1. Prepare the environment

Follow these steps:

Install the CLI for your operating system by following the steps outlined here.
Create a simple Hoverfly Simulation with a single endpoint by following step 1 in Tutorial 1: Create a service and simulation manually. Do not create the service, only the simulation.
Once the simulation is created. Navigate back to the Dashboard.

Part 2. Start a Service from the hcc CLI

Follow these steps:

If you followed the previous steps you should have a saved simulation called product-sim. Now we will start a service that uses that simulation.
- Execute the following hcc command from the command line to start a service called product with that product-sim simulation.
  hcc service start product --simulation-name product-sim
- If you refresh your Dashboard you will see a new service with the name product starting up.
Test the running service by hitting the single endpoint with your API client: https://product-youraccounthere.hoverfly.io/product/12345

You can remotely manipulate services, simulations and scenarios with hcc, as well as use it as a local proxy to capture local API traffic, or as a local reverse proxy proxying to Hoverfly Cloud. A summary of the commands is as follows:

Usage:
  hcc [command]

Available Commands:
  capture            Commands for interacting with local capture proxy
  config             Get/set CLI config properties
  help               Help about any command
  reverse-proxy      Commands for interacting with local reverse proxy proxying to Hoverfly Cloud
  scenario           Commands for interacting with Hoverfly Cloud Scenarios
  service            Commands for interacting with Hoverfly Cloud Services
  simulation         Commands for interacting with Hoverfly Cloud Simulations
  version            Get the version of Hoverfly Cloud CLI

Flags:
      --api-token string   API token from Hoverfly Cloud
      --domain string      Domain name of Hoverfly Cloud
  -h, --help               help for hcc
      --insecure           Allow reverse proxy to private Hoverfly Cloud deployment without certs

hcc cannot control all the settings in Hoverfly Cloud however, for that you need to use the REST API directly.

Part 3. Use the Hoverfly Cloud API to retrieve information about a service

Follow these steps:

Where there are functional limitations with hcc, all functionality available within Hoverfly Cloud can be accessed via the Hoverfly Cloud API.
The Hoverfly Cloud API uses hypermedia and resources include links to other related resources in their responses using the Hypertext Application from resource to resource. Language (HAL) format.
With the product service running in Hoverfly Cloud, issue the following GET request to the Hoverfly Cloud API to retrieve information about your running service:
https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/<<user-name>>/hoverflies/product
- You will need to add a bearer token containing your API key in a header called Authorization. The API key can be retrieved from your Account page in Hoverfly Cloud.
- eg. curl -H "Authorization: Bearer 7254a454c7123454593jgjae06a17025a7" https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/<<user-name>>/hoverflies/product

You will receive a response similar to this:

{
    "name": "product",
    "createdBy": "user-name",
    "createdDate": "2023-06-16T15:04:45Z",
    "dnsName": "product-yourUID.hoverfly.io",
    "status": "PAUSED",
    "instanceCount": 1,
    "simulation": {
        "name": "product",
        "uuid": "d01225d16a5e44fd882243fa14449b6e",
        "versionId": "64854b1684be4acd8991db1d960f57b1"
    },
    "mode": "simulate",
    "_links": {
        "self": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/user-name/hoverflies/product"
        },
        "journal": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/user-name/hoverflies/product/journal"
        },
        "time-series": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/user-name/hoverflies/product/timeSeries"
        },
        "simulation": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/user-name/hoverflies/product/simulation"
        },
        "behavior": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/user-name/hoverflies/product/behavior"
        },
        "stats": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/user-name/hoverflies/product/stats"
        },
        "diff": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/user-name/hoverflies/product/diff"
        },
        "reset": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/user-name/hoverflies/product/data"
        }
    }
}

While this gives you information about the service, it's status and the simulation it is using, it also give you links to other resources on the Hoverfly Cloud API related to the management of the product service. Let's add some behavior.

Part 4. Adding behavior to a running service

Follow these steps:

If you issue a request to the link to the behavior endpoint returned by the query to the service endpoint above, you will receive an error, as there are no configured behaviors as yet for this service. We will add a 40% chance of a 404 Response code and a latency histogram behavior.

Issue the following PUT request with the same Authorization header as before, and with a json Request body as follows:

{
    "behaviors": [
        {
            "name": "randomStatusCode",
            "config": {
                "statusCodes": {
                    "404": 0.4
                }
            }
        },
        {
            "name": "delayByHistogram",
            "config": {
                "latencies": [
                    100,
                    200,
                    400
                ]
            }
        }
    ]
}

If successful you should receive a response similar to the below:

{
    "name": "product",
    "createdBy": "your-account",
    "createdDate": "2023-08-15T13:40:03Z",
    "dnsName": "product-youUID.hoverfly.io",
    "status": "RUNNING",
    "instanceCount": 1,
    "simulation": {
        "name": "product-sim",
        "uuid": "97f93d32644d40b785187cf42563c620",
        "versionId": "49f6d6c653f54103a9c76fda3814e849"
    },
    "mode": "simulate",
    "behaviorEnabled": true,
    "_links": {
        "self": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/your-account/hoverflies/product"
        },
        "journal": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/your-account/hoverflies/product/journal"
        },
        "time-series": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/your-account/hoverflies/product/timeSeries"
        },
        "simulation": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/your-account/hoverflies/product/simulation"
        },
        "behavior": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/your-account/hoverflies/product/behavior"
        },
        "stats": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/your-account/hoverflies/product/stats"
        },
        "diff": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/your-account/hoverflies/product/diff"
        },
        "reset": {
            "href": "https://cloud.hoverfly.io/hoverfly-cloud/api/v1/users/your-account/hoverflies/product/data"
        }
    }
}

Part 5. Test the modified service

Follow these steps:

Refresh the Dashboard
Notice that the product service line now has a magic wand icon. This indicates that behaviors are now in play. Click it to open the behaviors dialogue.
You will notice that the behaviors are configured as set via the API.
Test the running service by hitting the single endpoint with your API client: https://product-youraccounthere.hoverfly.io/product/12345
You should receive Not Found errors 40% of the time and the latency should be noticeable.
Note that the API is extensive and covers all areas of functionality for Hoverfly Cloud. If it can be done through the management portal it can be done through the API.

Part 6. Remove the service and simulation

Follow these steps:

Unless you want to keep the service and simulation, they can be deleted.
To delete the service and it's copy of the simulation navigate to the Dashboard, open the ellipse to the right of the product service that you created, and select Delete.
To delete the master simulation, navigate to the Simulations page, locate the simulation you created, and click the corresponding x at the right of page.

Congratulations! You have completed this Tutorial, "Using the CLI and the Hoverfly Cloud API"

PreviousAutomating with the CLI and API

Last updated 8 months ago