Feature: Add incremental deploys

[Joost Jansky]

Description

If you want to add a single file to a site, you currently have to

1. Fetch all files from a site with /sites/{site_id}/files
2. Add the new file to the file list
3. Send the full file list with POST /sites/{siteId}/deploys
4. Deploy the all required files with PUT /deploys/{deployId}/files/{path}

This process is not only error prone, it also leads to a lot of unnecessary network traffic, especially for long file list. The proposed feature aims at improving and simplifying this process.

Feature

At a minimum steps 1. + 2. are not needed with a new version of /sites/{siteId}/deploys. This new version could have the following signature:

PATCH /sites/{siteId}/deploys
Parameters: sha keys of all files that should be added to the existing files
Return: same as before: list of required files for upload and a new deployId

Step number 4 would still be necessary, if an upload is required.

Alternatives

Maybe it is possible to avoid steps 1.-3. altogether with an improved version of PUT /deploys/{deployId}/files/{path}, theerby simplifying the process even further.

Note: This is a feature request for the API core functionality and not a spec issue.

[Marcus Weiner]

Please note that this change is unlikely based on the atomic nature of deploys and several implications in the system, especially around deploy previews / branch deploys.

PATCH /sites/{siteId}/deploys
Parameters: sha keys of all files that should be added to the existing files

which list of "existing files" should this extend?
every deploy has its own list of files, there is no list of files for a site object.

[Joost Jansky]

It should be the current, active deploy (/sites/{site_id}/files also works without a deployId). If that is a problem you could require to specify a deployId.

Another way to think about this is to look at git (which I think is also doing atomic operations). To add one file to an existing repository you just need to do git add {file} followed by git commit. There is no need to first get all existing files of that repository and specify them in git add, it works incrementally.

[Marcus Weiner]

It should be the current, active deploy (/sites/{site_id}/files also works without a deployId).

That would mean it would only work for production deploys. This could be a footgun if you don't mean to update your production deployment.

Nonetheless, thank you a lot for the suggestion.
I think our product team will consider this for prioritization, but it's unlikely our team will work on this anytime soon.

[Joost Jansky]

Seems like I was blind and adding one file to an existing deployment is already possible without creating a new deploy. It can be done with:

PUT /sites/{site_id}/deploys/{deploy_id}

Sorry for generating unnecessary traffic. Thanks a lot for your prompt replies, please close this issue.

[Marcus Weiner]

this is likely not true. remember, deploys are atomic.
once you uploaded all required files for a deploy the deploy is being published and you can no longer call that endpoint for it.

[Joost Jansky]

Thanks for pointing this out, you are correct: the above PUT endpoint only works on unpublished deploys. So, atomic deploys means that a deploy is immutable after being published. I fully agree that any feature request should not change this property of the current system architecture.

I still think this property can be preserved, here is a new, slightly modified proposal for incremental deploys:

PATCH /sites/{siteId}/deploys/{deployId}

1. Request Body includes only new files and functions
2. Return: a new deployId, required files and functions
   (Internally, your system adds the existing files, functions of old {deployId} to the new stage corresponding to new deployId)

Upload will be the same and should be done with PUT /deploys/{deployId}/files/{path}.

@mraerino: Please let me know, if you see a chance in getting this feature considered.