Handling API requests for data stores

Before sending requests to Open Cloud APIs for standard data stores and ordered data stores, you need to understand how to handle them properly. For information on the usage of the API, see the Usage Guide.

Authorization

Like all Open Cloud APIs, data store endpoints require all requests to include the x-api-key header, which contains an API key with enough permissions for the request. This requires you to apply the key to the experience and the data store, and the endpoint operation is permitted. If the key is invalid, 403 Unauthorized is returned. For more information on API keys, see Manage API keys.

Throttling

Rate limits for the Open Cloud v1 Data Stores API are identical to the v2 limits.

Input validation

Before sending your request, make sure to validate endpoint parameters on formatting requirements and constraints based on the following table. Individual endpoints can have additional requirements beyond these. If a parameter doesn't satisfy the following restrictions, the endpoint returns a 400 Bad Request.

Ordered Data Stores endpoints use Percent-Encoding for all query and body parameters. Unless you have special characters in your parameter values that break URLs, you don't need to handle encoding yourself.

Input	Type	Notes
universeId	number	The unique identifier of your experience. See Universe ID.
datastoreName	string	Length must be 50 bytes or less. Can't be null or empty.
scope	string	The scope of a data store. See Scopes. Length must be 50 bytes or less.
entryKey	string	Length must be 50 bytes or less. Can't be null or empty.
content-md5	string	The base-64 encoded MD5 checksum of content. See Content-MD5.
roblox-entry-attributes	string	Serialized by JSON object. Length must be less than 300 bytes.
roblox-entry-userids	String	Serialized by JSON array of 0-4 numbers. No more than 4 user IDs.
cursor	string	An indicator of more data available in the requested result set. See Cursors.

Universe ID

The Universe ID is the unique identifier of the experience in which you want to access your data stores. The value of an experience's Universe ID is the value of its DataModel.GameId, not the same as the Starting Place ID, which identifies the starting place of an experience rather than the entire experience.

You can obtain the Universe ID of an experience with the following steps:

Navigate to the Creator Dashboard.
Find the experience with data stores that you want to access.
Hover over the experience's thumbnail, click the ⋯ button, and select Copy Universe ID.

Scopes

You can organize your data stores by setting a unique string as a scope that specifies a subfolder for the entry. Once you set a scope, it automatically prepends to all keys in all operations done on the data store. Scopes are optional and by default as global for standard data stores but required for ordered data stores.

It is strongly recommended to use the prefix parameter instead of scope for sorting and listing standard data stores.

The scope categorizes your data with a string and a separator with "/", such as:

Key	Scope
houses/User_1	houses
pets/User_1	pets
inventory/User_1	inventory

All data store entry operation methods have a Scope parameter for when you need to access the entries stored under a non-default scope. For example, you might have a 1234 key under the default global scope, and the same key under special scope. You can access the former without using the scope parameter, but to access the latter, you have to specify the scope parameter as special in Get Entry or Increment Entry API calls.

Additionally, if you want to enumerate all the keys stored in a data store that has one or multiple non-default scopes, you can set the AllScopes parameter in List Entries method to be true, in which case the call returns a tuple with key string and scope. In the previous example, the List Entries would return both (1234, global), and (1234, special) in the response.

You can't pass Scope and AllScopes parameters on the same request, otherwise the call returns an error. Leveraging the helping functions from the Open Cloud APIs for data stores module, the following code illustrates how you can read every key in a data store with a custom scope:

List Keys for Different Scopes
# Set up
import tutorialFunctions
DatastoresApi = tutorialFunctions.DataStores()
datastoreName = "PlayerInventory"

# List keys for global scope
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "global", allScopes = False)
print(keys.content)
# List keys for special scope
specialScopeKeys = DatastoresApi.list_entries(datastoreName, scope = "special", allScopes = False)
print(keys.content)
# List keys for allScope set to true
specialScopeKeys = DatastoresApi.list_entries(datastoreName, allScopes = True)
print(specialScopeKeys.content)

Keys with the corresponding scope are returned in the response:

Example Responses for Different Scopes
// Response for global scope
{ "keys": [{ "scope": "global", "key": "User_2" }], "nextPageCursor": "" }

// Response for special scope
{"keys":[{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

// Response for AllScopes
{"keys":[{"scope":"global","key":"User_3"},{"scope":"global","key":"User_4"},{"scope":"global","key":"User_5"},{"scope":"special","key":"User_6"},{"scope":"special","key":"User_7"}],"nextPageCursor":""}

Content-MD5

Content-MD5 is the base-64 encoded MD5 checksum of content. It's an optional request header for the Set Entry endpoint that checks the data integrity and detects potential issues.

If you don't include the content-md5 header in your request, there is a chance, though low probability, that you might experience data corruption.

You can use the language of your choice to calculate the value of the content-md5 header. The following example uses Python. The hashlib.md5() and base64.b64encode() functions are available in Python standard libraries (2.7, 3+).

Generating Content-MD5
# With prompts
$ python -c "import base64, hashlib; print('content-md5: ' + str(base64.b64encode(hashlib.md5(bytes(input('content: '), encoding='utf8')).digest()), encoding='utf8'))"
content: 750
content-md5: sTf90fedVsft8zZf6nUg8g==
# Using just stdin and stdout
$ echo "750" | python -c "import base64, hashlib; print(str(base64.b64encode(hashlib.md5(bytes(input(), encoding='utf8')).digest()), encoding='utf8'))"
sTf90fedVsft8zZf6nUg8g==

If you run into issues generating a valid content-md5 value, you might need to encode your request body in UTF-8 binary before computing the checksum.

Cursors

Endpoints that return lists of data might also return a nextPageCursor string. This indicates that there is more data available in the requested result set. To receive it, provide this string in the cursor query parameter on a subsequent request. If the cursor parameter is provided but invalid, the endpoint returns 400 Bad Request.

The format of cursor strings is not defined. You should not interpret or parse them as they may change at any time.

Filters

When sending requests to the List method for ordered data stores, you can add an optional filter query parameter to return entries with values in a specified range.

The filter parameter supports one logic operator, &&, and two comparison operators, <= for setting the maximum value and >= for setting the minimum value. If you want to set a range with both a max and min value, add && between the two sequences.

For example, to return entries with values that are less than or equal to 10, you need to input entry <= 10 as the filter value. To return entries with values between 10 and 50, input entry <= 50 && entry >= 10.

To input a valid filter value, you need to format all filter strings with a whitespace between each part of the sequence. The left part of each sequence must start with 'entry', and the right part must have a numerical value. Filter strings are also case-sensitive.

The following examples are incorrect filter values that can fail your requests:

entry <= 10 - no whitespace between each part of the sequence.
10 <= entry - entry and the comparison value are on the wrong side.
entry <= 10 && entry <= 50 - && can only be used to specify a range with both two comparison operators for the min and max value.

Allow missing flags

When sending requests to the Update method to update an existing ordered data store entry, you can add an optional allow_missing flag to allow the creation of an entry even if the entry doesn't exist.

When you set the allow_missing flag to True:

If the entry doesn't exist, the response returns a new entry.
If the entry exists but the content matches the existing value of the entry, the existing entry remains unchanged.
If the entry exists and the content doesn't match the existing value of the entry, the response returns the entry with the updated new content value.

On this page