Fly API

Channeling an API magically

Introduction

Using the Fly API, you can have code-level control over our powerful Application Delivery Network.

Within our global network of load balancers, you'll be able to…

  • Provide Let's Encrypt HTTPS to hostnames. Jump!
  • Add backends. Jump!
  • Configure routing rules. Jump!

This API follows the JSON API specification and transmits securely over HTTPS.

API Endpoints

Authorization

In order to authorize your API calls, the first thing you'll need to do is authenticate. To do that, you must have your [API_TOKEN]. To get it, login to Fly.io, click Your Account, then Personal Access Tokens on the sidebar. Once generated, you can authenticate by passing the Authorization: Bearer header along with your [API_TOKEN]. You'll need this to make API secured API requests.

Here's an example:

curl -H "Authorization: Bearer [API_TOKEN]" -X GET https://fly.io/api/v1/sites/:slug/hostnames

Hostnames

[POST, GET] : /api/v1/sites/:slug/hostnames

Each site is an umbrella that contains many hostnames. You can check-out the hostnames that belong to a site by sending a GET request to /api/v1/sites/:slug/hostnames, where :slug is name of the site you have created.

For example:

curl -X GET https://fly.io/api/v1/sites/:slug/hostnames

To create a new HTTPS hostname under your site, send a POST with an attached JSON body, like so:

{
  "data": {
    "attributes": {
       "hostname": "[NEW_HOSTNAME]"
    }
  }
}

A properly structured POST will look like this, plus authorization:

curl -H "Content-Type: application/json" -X POST -d '{"data": { "attributes": { "hostname": "[NEW_HOSTNAME]" } } }' http://fly.io/api/v1/sites/:slug/hostnames

An HTTPS Fly.io preview_hostname will be created with a fresh Let's Encrypt SSL certificate for each hostname that's been created. The final step is to setup a DNS record to link the preview_hostname with your domain of choice.

[GET] : /api/v1/sites/:slug/hostnames/:hostname

To view a specific hostname, you can send a GET request to that specific hostname resource.

curl -X GET /api/v1/sites/:slug/hostnames/:hostname

Backends

[POST] : /api/v1/sites/:slug/backends

You can use the API to create new backends for your sites. You'll need to pass a JSON body along with your request.

Here's an example using GitHub Pages:

{
  "data": {
    "attributes": {
      "name": "[BACKEND_NAME]",
      "type": "[BACKEND_TYPE]",
      "settings": {
        "repository": "[GITHUB_USER/GITHUB_LOGIN]"
      }
    }
  }
}

You can use whatever name you wish when you specify [BACKEND_NAME]. For [BACKEND_TYPE], ensure it matches below. The list of settings are the values that you can modify. The values for the settings expect typical inputs, for example repository would expect: githubuser/reponame.github.io.

Backend Backend Type Settings
AWS Lambda aws_lambda region, function_name, access_key_id
Amazon S3 aws_s3 bucket, region
Google Cloud Function google_cloud_function region, function_name, project_id
Ghost Blog ghost ghost_subdomain
GitHub Pages github_page repository
Squarespace squarespace squarespace_domain
Heroku heroku heroku_app

A properly structured POST will look like this, plus authorization. A reminder that :slug is the name of the site that you're adding the backend under:

curl -H "Content-Type: application/json" -X POST -d '{ "data": { "attributes": { "name": "[BACKEND_NAME]", "type": "[BACKEND_TYPE]", "settings": { "repository": "[GITHUB_USER/GITHUB_LOGIN]" } } } }' https://fly.io/api/v1/sites/:slug/backends

Once complete, you'll receive an id in return. You'll need this id in order to POST to /rules/.

Rules

[POST] : /api/v1/sites/:slug/rules

Once a backend has been established, you can leverage Fly's powers of fast global load balancing by creating rules. You can think of this like an API to a very capable proxy. You'll need to pass along a JSON body with your request. All backend rules have the same attributes.

Here's a general example:

{
  "data": {
    "attributes": {
      "hostname": "[HOST_NAME]",
      "backend_id": [BACKEND_ID]",
      "action_type": "rewrite", // Can be "rewrite" or "redirect".
      "path": "/", // Path to match. For example /blog/.
      "priority": null, // Integer or null.
      "path_replacement": null // Just like in the UI, specify the redirect path.
    }
  }
}

A properly structured POST will look like this, plus authorization. A reminder that :slug is the name of your site.

curl -H "Content-Type: application/json" -X POST -d '{ "data": { "attributes": { "hostname": "[HOST_NAME]", "backend_id": "[BACKEND_ID]", "action_type": "rewrite", "path": "/", "priority": "null", "path_replacement": "null"  } } }' https://fly.io/api/v1/sites/:slug/rules

Tips

We've got a couple hot tips!

  • Seeking a slick way to version your API? We have some neat ideas.

  • Using curl? Pipe your commands into python -mjson.tool to have them print prettily: curl -X GET ~~~ | python -mjson.tool.

Disclaimer

This API is currently under heavy development.

If you run into any oddities or need more flexibility for your use-case, please contact us: support@fly.io.