Add definition for /sites/id/rollback.

[calavera]

This endpoint reverts the production deploy for a site to the previous successful production deploy.

Signed-off-by: David Calavera [email protected]

[netlify]

Deploy preview for open-api ready!

Built with commit 24a8d4b

https://deploy-preview-265--open-api.netlify.app

[rstavchansky]

I'm pinging @kschlarman for context on this. While I ❤️ that we're adding an actual summary and description to this endpoint, I want to acknowledge that providing this information will make it differ from existing endpoints. Specifically, my concern is that the summary will look different than older endpoints, and this will make things inconsistent and therefore a little jarring.

While we're still in the transition stage before unleashing a beautifully documented new API site, I suggest that new endpoints added to our current reference site maintain the same summary naming structure. In this case, that would make this rollbackSiteDeploy, I believe.

I recommend keeping the description, as any explanation info is useful, and it's less distracting to have this available than to change the summary naming structure.

[rstavchansky]

IF we choose to keep the new type of summary wording, note that the deploy that's rolled back is singular, so I'd suggest changing this summary wording to Rollback production deploy

IF we choose to maintain the the existing summary format (my recommendation), I think this would need to be rollbackSiteDeploy.

[calavera]

I want to acknowledge that providing this information will make it differ from existing endpoints. Specifically, my concern is that the summary will look different than older endpoints, and this will make things inconsistent and therefore a little jarring.

What's the worse thing that can happen if we don't change it? Are customers really going to be confused by a summary that's more friendly than the rest to the point that they don't use the API, or don't understand it?

[rstavchansky]

The worst that could happen is that we'd create an inconsistent reference experience and a false expectation that we'll be providing more information for our endpoints on this API docs site, which we don't currently have a plan to do. This doesn't prevent a user from using this API. Regardless, the resource should be singular (deploy). This observation isn't a "we really must not do this" statement, but more of an acknowledgement that by making some of our API reference marginally better, we may end up making the rest of it look worse by contrast.

[rstavchansky]

I'm approving as-is, but I was trying to make the point that adding a description would be useful and not so distracting. But that using a new summary format would be distracting. Feel free to the description back in if you're wanting to be charitable to our users and provide more context for this endpoint usage.