Hi Creators,
We’re excited to share the Beta release of a new and improved version (v2) of the Data Stores Open Cloud APIs. With this new version, we’ve implemented stylistic changes to increase consistency with the rest of Open Cloud endpoints. We’ve also added various quality of life changes (with your feedback – thanks!) which should make working with the Data Stores via Open Cloud a breeze.
Data Stores v2
With the Data Stores v2 endpoints, we’ve made some changes with the goal of bringing them in line with our current API design guidelines and moving Open Cloud towards more overall consistency. With two exceptions (see section below), there are no changes to functionality.
You can view the documentation for the Data Stores v2 endpoints under the Open Cloud API Reference here.
Note: please consider these endpoints as the official method of accessing Data Stores outside of Roblox Studio/experiences. (We’ll soon sunset support for historical unofficial access of Data Stores via hitting undocumented Roblox APIs, i.e. gamepersistence)
Functional changes
The only functional changes being made in Data Stores v2 are:
- Numeric values are now doubles and clamped to the range [2^53, -2^53].
- Increment operations now have a default increment amount of 1 (previously, the default was 0).
Structural changes
This table describes how certain functionality from datastores/v1 is supported in cloud/v2.
| datastores/v1 | cloud/v2 |
|---|---|
| SetEntry | CreateEntry; UpdateEntry with UpdateDataStoreEntryRequest.allowMissing = true |
| ListDataStoresRequest.prefix | ListDataStoresRequest.filter (example: id.startsWith(“foo”)) |
| ListEntriesRequest.prefix | ListDataStoreEntries/ListDataStoreEntryRevisions.filter (example: id.startsWith(“foo”)) |
| ListEntriesRequest.allScopes | Collection wildcard (…/scopes/-/…) |
| SetEntryRequest.matchVersion | DataStoreEntry.etag |
| EntryVersion.deleted | DataStoreEntry.state |
| ListEntryVersionsRequest.minValue, ListEntryVersionsRequest.maxValue | ListDataStoreEntryRevisionsRequest.filter (supporting &&, <=, >=) |
| ListEntryVersionsRequest.sortOrder | ListDataStoreEntryRevisionsRequest.orderBy |
| GetEntryVersion | GetEntry with @revisionId appended to the path (example: GET cloud/v2/universes/123/data-stores/456/entries/my-entry@789) If your entry ID contains the @ symbol, you can use the special revision ID “latest” in order to get the latest version of that entry (preventing part of the ID being interpreted as a revision ID). For example, GET …/entries/foo@bar@latest will get the latest version of the entry with ID foo@bar. |
Ordered Data Stores v2
You can view the documentation for the Ordered Data Stores v2 endpoints under the Open Cloud API Reference here.
The changes from ordered-data-stores/v1 are minimal, though useful. Here’s what’s changed:
- Ordered Data Stores is now on cloud/v2, rather than a separate endpoint.
- Collection names are now kebab-cased rather than camelCased, in part due to your feedback from the release of ordered-data-stores/v1. Thanks! (This means that cloud/v2 uses resource paths like universes/123/ordered-data-stores/some-ordered-data-store/entries, rather than universes/123/orderedDataStores/some-ordered-data-store/entries.)
- Values are now doubles rather than int64s, and values will be clamped to the safe integer range for a double: [2^53, -2^53]. This reflects the fact that Luau only supports doubles, and we want to discourage precision bugs resulting from using larger numbers.
- Create and update operations without an explicitly provided value are now rejected (previously, they defaulted to value == 0).
- Increment operations now have a default increment amount of 1 (previously, the default was 0).
- The List operation orderBy argument now is now set using value and value desc (instead of asc and desc). This will allow us to support ordering for other fields and resources in Open Cloud with a standardized syntax.
- The documentation of the Increment method has been corrected to reflect existing behavior present in ordered-data-stores/v1: Entry values can be incremented past the valid range, and this may be persisted in the backend, but returned values will be clamped to the valid range.
That’s all, Creators! Our vision for Open Cloud is to give creators a standardized API surface for all of Roblox, and we hope these stylistic changes bring us closer to that goal. Please try out the new-and-improved Data Stores v2 endpoints and let us know what you think. We can’t wait to see what they’ll help you build.
