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.
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.
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.
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.
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.
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.
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?
Hi! I have a question about the “Update Machine” endpoint. Is it possible to make that a PATCH endpoint? Also, is the current_version property in the request body a read-only property?
“update machine” is POST because it is actually implemented as “create new machine version”. the current_version in the body is used to fail the request if the actual current version is not the one specified in the request.
the docs could probably get clarified a bit on this?
Oh, that’s interesting! I definitely think that the docs should clarify this. But I am wondering when this endpoint should be used? Is this meant to be used when users want to update a machine?
Also I didn’t understand the part about current_version. What is the actual current version supposed to be?
@lillian I am getting back to working on the Pulumi provider purely based on the Machines API. My goal is to go from OpenAPI spec to a fully-working Pulumi provider with as few modifications as possible. One that note, I found two issues with the latest spec:
The update machine endpoint requires a current_version property in the request payload. However, neither the create machine nor the get machine endpoints return that version. I do see a list versions endpoint but it is a bit inconvenient to use to get the current version; not to mention nothing indicates what the current version really is.
The endpoint path /apps/{app_name}/machines/{machine_id}/metadata has a PATCHand a PUT that have the same operation ID. Also, from what I can tell both endpoint methods seem to do the same thing. Is PUT supposed to replace all metadata vs. PATCH to update only the metadata that is included in the request body, i.e. per REST conventions?
…before I start a new topic.