Fly Machines REST API OpenAPI Specification

I’m trying to get started using the Fly machines API and I’ve been looking for an OpenAPI Specification to generate clients for the REST API.

Unfortunately, I didn’t find anything in the docs so far. Is this available somewhere else or is this something that is planned for the future?


1 Like

Hi @tiwi,

We’ve definitely talked about providing an OpenAPI spec at some point and it’s good to know it’d be useful. Right now, we don’t have an eta on when that would be available though.

@JP_Phillips – if you need any help creating one you can use Optic GitHub - opticdev/optic: Optic makes it easy to document your APIs, prevent breaking changes, and follow an API style-guide – I know some of the Backstage folks used it to get caught up too.

1 Like

A OpenAPI specification would be super useful, should have priority over writing documentation imo

OpenAPI spec and Orval allow us to fly! :smile:

Here’s an initial draft of an OpenAPI spec. The actual swagger 2.0 json file is here. If needed, you can convert it to OpenAPI 3.0 using the swagger converter.

cc @dphuang2


If the end goal is to generate SDKs for the API I would suggest:

  1. Adding tags to operations for namespacing in generated docs/sdks Grouping Operations With Tags
  2. Operation ids that follow “[tag]_[operationId]” convention: Naming your Operation IDs for better SDK Method Names | Konfig
1 Like

I tried generating a client using autorest but it did not like the enum definition with duplicate entries. I was able to fix it manually. Having a 3.0 spec available via URL would be nice to feed it directly into the tooling and maybe even run CI notifications if the spec changes.

Updated with tags and better operation IDs, and fixed the Duration enum that broke autorest generation:

Just wanted to say hell yes + thanks for this! (Really like the workflow of testing with Postman + then generating API calls from that)


FYI finding the machines exec API does not support a command:string[] parameter as documented, only the cmd:string.

Also can’t seem to figure out how to run a compound command that includes an && or > in it via the machines exec API (or CLI):

% fly machine exec MY_MACHINE_ID "echo whatup && ls"
whatup && ls

Is there an alternative way of formatting to accomplish this? (I basically want to dynamically write out a file onto the machine and first thought on quick&dirty approach was to use >)

thanks, will fix that

You need to run it inside bash, like so:

% fly machine exec MY_MACHINE_ID "bash -c 'echo whatup && ls'"

Seems to work for me. Can you share your body?