Thanks for the feedback! I’ll give detailed answers to some of these points where I can (also aware I’m skipping some - I’m not the right person to answer everything).
- Why is the Restart Servers API done with a
{universeId}:restartServers
instead of{universeId}/restart-servers
or the like? This seems like a weird decision.
In general, we want to have a syntactic distinction between resources/collections and methods in Open Cloud. The standard CRUD methods (GET/POST/PATCH to resources or collections of resources) don’t require this, but we want to make it impossible for custom methods like :restartServers
to be confused with (or even collide with) subresources.
In this case you can read “/restart-servers” and recognize that it’s a verb phrase and so probably a method and not a resource or collection, but that’s semantic rather than syntactic.
Why is a field mask needed instead of partial JSON?
This is a convention that we’ve adopted in general in Open Cloud. There are definitely some tradeoffs, and unfortunately I can’t get into all the details on this one, but we think this is the right long-term approach.
Since you can set Private Server prices, why is there nothing for setting Paid Access prices?
This is good feedback. We might have had a good reason for leaving it out, I don’t remember (but some other staff member might), but perhaps it’ll come in the future.
Personally, I would prefer a separate flag for if Private Servers are enabled or not, rather than setting the price to null.
This would potentially result in ambiguous or invalid configurations, like private servers being disabled but having a nonzero price. What does it mean to change the price while leaving private servers disabled? We wanted to make it harder to express states and operations don’t really mean anything. If a price is meaningful if and only if private servers are enabled then it’s redundant to have two fields.
This is a debatable point of API design philosophy, of course, and we certainly could have done it the way you suggest. Just sharing a bit of our thought process.
Short of it is, we have GitHub actions that deploy new copies of our entire experience and it’s places for testing pull requests. I currently use some odd old APIs and worry that they will get removed at any moment.
We do recommend migrating to Open Cloud when possible - that’s where the majority of our future investment and active support for public APIs will be. But we don’t have any plans to suddenly remove anything without sufficient warning, and we don’t want to break people’s workflows.