Fugue REST API

What is a RESTful API?

RESTful APIs operate programmatically via HTTP (defined by RFC 2616) and use a number of stateless operations (PUT, DELETE, POST, etc…) to interact with resources. Learn more about them here, or check out a tutorial here.

If you’re ready to skip ahead, go here for the full Fugue API Reference.

How Does It Work?

Fugue’s RESTful API enables users to take advantage of REST clients (Postman, Insomnia, Paw, etc.) or HTTP clients (curl) to issue Fugue commands and manage cloud infrastructure. The API benefits customers that want to integrate Fugue into new or existing workflows (e.g. CI/CD, service catalog, etc.) or those customers who may want to provide their own user interface on top of Fugue. In either scenario a user can simply issue fugue server run to launch an HTTP server and begin using commands. Learn more about the server command here.

How Do I Get Set Up?

Install Fugue & Launch a Conductor

You will need to have Fugue installed and a Conductor running. If you still need to get set up, check out the Quick Start Guide.

Note: Any server you launch is configured on your local host, and nothing is installed on the Conductor itself.

Set an Environment Variable

Export an environment variable to access the fugue server command:

export FUGUE_BETA_API=true

Authentication

The Fugue API server uses Fugue user credentials for authentication. Fugue searches for the credentials file in these locations.

Authentication is handled in one of two ways. You may:

  • Pass your RBAC (Fugue) profile credentials in each HTTP request, using Basic Authentication. This scenario is useful for a setup with multiple users with differing levels of access to run commands. By default, the server runs without a credentials profile, so authentication is provided by the client. Your Fugue user (RBAC) credentials must be included in every HTTP request header.
  • Or, specify a Fugue user profile with the use of --profile when you issue the fugue server run command.
    • Note: For this option to work, the Conductor must be installed, and the profile must exist in your credentials file.

Once a server is started, if the --profile option is used, authentication passed in HTTP headers is ignored. Learn more about the server command here.

Note: If you encounter a 401 unauthorized error when attempting an action this typically indicates that your user does not have the appropriate Fugue/RBAC permissions.

Sending API Requests

Use your preferred client to send API requests to the Fugue API server. You can consult our API Reference for the API path and method corresponding to the Fugue command you want to execute.

For example, executing curl http://127.0.0.1:8080/api/v0/processes will return the Fugue status of all processes.

Or check out a walkthrough to learn how to use the Fugue API to create and manage a process programmatically over HTTP.

Create a Snapshot

A snapshot is an archive file that includes a composition, all of the required files to compile it, and any associated environment variables. This is the compilation output that the Conductor needs in order to create a new process. It is an output format within lwc that supports the relationship between the Fugue API and the Ludwig Compiler. The snapshot functionality is only necessary for scenarios where the Fugue Conductor will be uploading a composition including:

  • run
  • update
  • policy rbac-attach
  • policy validation-create
  • dry-run for the run and update commands

Note: Snapshot files must be suffixed .tar.gz (e.g. name.tar.gz) for the Conductor to recognize them.

Request a Dry-Run

Fugue supports dry-run on four CLI commands:

To complete a dry-run of any of these commands over API, follow these two steps:

  1. Request a dry-run
  2. Get a dry-run result

1. Request a dry-run

First, you must send an API call requesting a dry-run. The command you’re dry-running is specified as a query parameter. Other query parameters may be required, depending on the command.

For example, the following curl command requests a dry-run of a composition snapshot titled HelloWorld.tar.gz:

curl -X POST http://127.0.0.1:8080/api/v0/dry-run?command=run -H 'content-type: application/x-tar' --data-binary @HelloWorld.tar.gz

The API server’s response might look like this:

{
  "id": "2b9b08b6-61dc-422a-95d4-44fa96db0bbb.3d550a8d-ed32-4e75-a60e-ba9160fe22b4",
  "link": {
    "href": "/api/v0/dry-run/2b9b08b6-61dc-422a-95d4-44fa96db0bbb.3d550a8d-ed32-4e75-a60e-ba9160fe22b4",
    "rel": "self"
  },
  "status": "accepted"
}
id
The ID of the results resource
link

Contains the href and rel fields

href
The path of the results resource
rel
The link relation type – in this case, self
status
The status of the API call – in this case, accepted

2. Get a dry-run result

The second step of the dry-run process is to retrieve the dry-run results.

Using the path returned from the previous step, you might use a curl command like this one:

curl http://127.0.0.1:8080/api/v0/dry-run/2b9b08b6-61dc-422a-95d4-44fa96db0bbb.3d550a8d-ed32-4e75-a60e-ba9160fe22b4

And in the response, you’d see the dry-run plan in JSON format:

{
  "fid": "2b9b08b6-61dc-422a-95d4-44fa96db0bbb",
  "job_id": "1511380257",
  "requests": [
    {

Output trimmed for length.

What Is Not Supported?

Fugue does not provide RESTful API support for the following commands:

  • init
  • install
  • uninstall
  • upgrade
  • user
  • support

If you have questions, reach out to support@fugue.co.

Where Can I Get More Information?

For details on fugue server refer to our page on the command or check out a walk-through of the Fugue API.

Take a look at the full Fugue API Reference here.