Machines OpenAPI spec omissions

, , ,
1

Hello! I have found errors in the OpenAPI spec. I am hoping someone from the dev team can address these.

The following GET endpoints are missing path parameter definitions under parameters:

/apps/{app_name}/certificates
/apps/{app_name}/certificates/acme
/apps/{app_name}/certificates/custom
/apps/{app_name}/certificates/{hostname}
/apps/{app_name}/certificates/{hostname}/acme
/apps/{app_name}/certificates/{hostname}/check
/apps/{app_name}/certificates/{hostname}/custom
/apps/{app_name}/ip_assignments
/apps/{app_name}/ip_assignments/{ip}

These endpoints are missing request body definitions:

PATCH /apps/{app_name}/machines/{machine_id}/metadata
POST /apps/{app_name}/machines/{machine_id}/metadata/{key}

Interestingly, the documentation on Machines API · Fly Docs actually shows the correct info for all of these endpoints. However, the scalar.com-generated docs https://docs.machines.dev/ is also missing information, which is unsurprising given that it’s generated from the API spec.

1 Like
3

I would also like to suggest/request PATCH /apps/{app_name}/machines/{machine_id}/metadata to be changed to use a PUT per REST conventions. The endpoint replaces a machine’s metadata with whatever is provided in the request body. PATCH is typically used when you want to only touch the properties in the request body and leave the unspecified properties intact on the resource. Since metadata is treated as its own resource, I really think PUT is more appropriate here.

As for POST /apps/{app_name}/machines/{machine_id}/metadata/{key}, I suggest adding the following methods to facilitate operations by metadata key:

GET /apps/{app_name}/machines/{machine_id}/metadata/{key} - Get a machine's metadata by key
POST /apps/{app_name}/machines/{machine_id}/metadata/{key} - Already exists.
PATCH /apps/{app_name}/machines/{machine_id}/metadata/{key} - Update a single metadata by key
DELETE /apps/{app_name}/machines/{machine_id}/metadata/{key} - Delete a single metadata by its key

For context, I am working on generating a Pulumi provider using your OpenAPI spec. Having a clear parent/child resource relationship helps with generating resources that communicate their intent clearly to users of the provider. I’ve written some information about how this model of generating Pulumi providers from API specs works if it helps.

4

thanks for your interest in Machines API! sure, we will add the request body schema to certificates/ip_assignments. I agree PATCH metadata should be PUT, we will also make that change.

1 Like
5

Hi @lillian, thank you for your response.

sure, we will add the request body schema to certificates/ip_assignments.

The GET endpoints in my original message are only missing the required path parameter definitions. They don’t need request bodies.

I agree PATCH metadata should be PUT, we will also make that change.

Awesome!

Also, I am curious if you have thoughts about the POST /apps/{app_name}/machines/{machine_id}/metadata/{key} endpoint and add full CRUD support for a metadata property by its key.

6

ah, I misunderstood, thanks for the clarification :+1:

I don’t see the reason for separating create/update as it’s the same operation (machine metadata is stored as a hashmap in our backend), but I suppose it makes sense to have an endpoint to fetch a single metadata key.

7

I don’t see the reason for separating create/update as it’s the same operation (machine metadata is stored as a hashmap in our backend), but I suppose it makes sense to have an endpoint to fetch a single metadata key.

Yeah that’s absolutely fair. For some context, I am working on a Pulumi provider generated from the API specs. It would be ideal if each create"able" resource has at least create, read and delete endpoints associated with it. An update endpoint would be a bonus.

8

Ooh, won’t this break existing users of this API? I think the normal approach is to reserve BC breaks for a new API version.

9

the secret is to not break existing users, and just add the new method and change the docs :​) for something like this, it’s fine.

1 Like
10

I see that this issue is still present in the live OpenAPI spec file. I like to keep my codegen pointed at the current spec so I get build failures if things break, but I can’t do that while this issue is present. By any chance do you have an ETA for when the spec will be updated?

11

hopefully some time this week but I can’t promise a timeline, sorry.

12

:waving_hand: @BenAtFantail / @praneetloke the issues should all be addressed now and live at docs.machines.dev. A GET metadata key endpoint has also been added.

Let us know if anything still looks amiss, and thanks again for pointing out the issues!

1 Like