Open Cloud Universes API

[PureBigMadBoatMan]

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.

[Noble_Draconian]

@appletree008

You can configure:

• Server size
• Voice chat settings
• Private server status
• Supported devices
• Restart all servers for updates

Can we get support for these?

• Place description & title
• Place thumbnails
• All game settings (avatar scale, R15 / R6, etc)
• Creating / updating devproducts, gamepasses & badges, as well as their associated metadata such as icons

This would allow tools such as mantle to switch away from using legacy APIs.

[ChasingSpace (Chasing)]

Thank you for the detailed response! This is very insightful.

@PureBigMadBoatMan

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.

After looking more closely at other Open Cloud endpoints, I can see there’s consistency with the methods approach and I better understand the approach. I actually like the distinction now that it’s been pointed out.

@PureBigMadBoatMan

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.

Thinking about it a bit more, especially with private server prices being able to be null, I think this makes a bit more sense. Since some JSON converters might exclude null values rather than explicitly specifying null, I think this approach makes sense since I assume it would see the price in the field mask but not in the JSON body, and infer that it’s being set to null.

Unsure if this is one of the purposes behind it or if it even works that way, haven’t tested it yet, but makes sense on paper.

@PureBigMadBoatMan

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.

I was mostly thinking of parity with the develop.roblox.com/v2/universes/{id}/configuration endpoint which has allowPrivateServers and privateServerPrice as separate fields. If I’m recalling correctly, if allowPrivateServers is false, privateServerPrice will always be zero.

I think your explanation makes sense though. Open Cloud is far more consistent in approach than prior iterations of Roblox APIs and it’s nice to get a glimpse of the standards in place. I can see this approach being particularly useful if there’s ever a more complex situation than simply private servers being enabled and what their price is.

@PureBigMadBoatMan

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.

Absolutely. I do my best to migrate to Open Cloud as soon as an applicable endpoint is available, however some stuff I’m suspecting might still need workarounds if designed without much flexibility.

My understanding is that there is a system in place to determine what should be intended for public use vs internal use which can be unfortunate to deal with, since public use APIs likely wouldn’t have the flexibility that I’d like to have.

For example, after creating a new universe for a pull request, I actually make a request to the API for modifying OC keys to give the key access to the new universe. This pretty clearly breaks the intent behind the key permissions entirely, but is a means to an end to be able to use OC at all because of permissions.

This is why I suggested the template universes where permissions can be extended without needing to modify the key permissions through the internal API. I imagine this structure would provide the flexibility for my use cases without needing to rely on the internal APIs which only authenticate with cookies.

At least with my current approach, it’s sufficient enough and I don’t need to worry about removal, only breaking changes because Roblox doesn’t expect people to be using them… so far so good though!

---

A quick aside - a public endpoint for sound permissions would be great, since it’d make it easier for external asset management tools (we built one in-house with the Assets endpoint) to grant permissions to sounds properly.

[parker02311]

When developer products API?? please??

[Azrellie (FxmboyStormie)]

Will we ever get an API that allows developers to get the amount of running servers, along with the players in said servers for certain games without the third party part?

[hya123456h (KingBob)]

This is what I’ve been waiting for. Now I just need to wait for the engine API to use all objects and I can finish my studio from anywhere project.

[bigtheangry]

everyone gangsta til they yoink your api key

[MetatableIndex]

I can’t seem to get restart servers to work. I am doing the http request correctly and it is returning null as expected in the documentation, but the servers don’t actually close / restart.

I am doing the format correctly, in fact I implemented this for MessagingService and it works just fine.
The permissions are all granted in the API key I’m using.

Is there anything I’m missing?

[itsrenderman (Render)]

Cool to see even more additions to open cloud!

[DevAX1T]

This is quite nice! But could we get an API endpoint to restart a specific server as well?

[ChasingSpace (Chasing)]

Just a guess, but it might only close outdated servers. Try updating the experience and then call the API, it might work then. It likely uses the same system as “Restart servers for updates” which does that.

[appletree008]

Yes, this is correct. This new endpoint works the same as the existing “Restart servers for updates”

[appletree008]

We understand this is important to many of you, and it is on our radar.

[appletree008]

Can we get support for these?

• Place description & title
• Place thumbnails
• All game settings (avatar scale, R15 / R6, etc)
• Creating / updating devproducts, gamepasses & badges, as well as their associated metadata such as icons

Place description and title support is included in this release
Place thumbnail updates are in the process of being released right now.
We have dev products, game passes, and badges on our radar. Badges is being actively worked on

[MetatableIndex]

Doesn’t work even if I update the place.
None of the APIs I’ve tried to work with for the Universes API seem to be working for me.

I am trying to add the ability to restart the servers and set a place’s visibility, but the APIs return the expected response but have no actual effect.

[appletree008]

Regarding restarting servers - did you make any changes to your universe? If not, this endpoint will not restart any servers (there is nothing to update). From the original post:
this is equivalent to using the “Restart servers for updates” feature on Creator Dashboard
If you did make changes, how did you verify that the servers were not restarted?

The universe visibility cannot be updated via these endpoints. We will work on updating our docs to make this more clear

[MetatableIndex]

@appletree008

Regarding restarting servers - did you make any changes to your universe? If not, this endpoint will not restart any servers (there is nothing to update). From the original post:
this is equivalent to using the “Restart servers for updates” feature on Creator Dashboard
If you did make changes, how did you verify that the servers were not restarted?

Hi, thanks for the quick reply.

I published a new version to the test place I am using for this while I was in-game in a server on it, and then tried using the endpoint to restart the servers. Nothing happened in-game, I was still in the server and it did not restart or migrate to a new server.

@appletree008

The universe visibility cannot be updated via these endpoints. We will work on updating our docs to make this more clear

That’s a bummer. This is the main reason I need the Universes API for as it would make it a lot easier to manage QA sessions and whatnot. Are there any plans on including support for this?

[appletree008]

Can you repro this issue via Restart servers for updates on CD?

One issue we have seen before is where the developer publishes an update, then joins the game (which is now on the latest published version), and then tries to restart.

Are there any plans on including support for this?

We would like to add support for this, but I am not sure what the timeline is looking like.

[MetatableIndex]

I joined the game before publishing the update, and it didn’t work. Not sure if I’m just doing something wrong on my end… I have a sample of the code I’m currently using here.