Patterns

Some Open Cloud endpoints utilize special patterns when making requests and receiving responses.

Pagination

If you specify maxPageSize in your request, some methods return paginated results—essentially partial responses:

GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}

If a response includes a value for nextPageToken, use that value in the pageToken parameter of the subsequent request to retrieve the next page. When nextPageToken is empty, you've reached the end of your results:

GET /cloud/v2/users/{userId}/inventory-items?maxPageSize=25&pageToken=aaaBBB

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}

Aside from the pageToken, you must use the same query for pagination to work properly. Altering any filter parameter results in a 400 error.

Content Length and Type

If your request includes a body, be sure to include the Content-Length and Content-Type headers. Most HTTP clients add these headers automatically.

Filtering

Some methods let you filter the response by including a filter parameter in the request. The following sections describe filter syntax and guidelines for the specified endpoints.

List Group Memberships

The wildcard character - can be used in place of group ID in order to list memberships across all groups: groups/-/memberships.

Filtering conforms to Common Expression Language (CEL). Only two operators are supported:

• ==
• in [...]

If you specify a group ID in the resource path, you can filter memberships by either user or role in the following formats:

• User filter: filter="user == 'users/9876543210'"
• Role filter: filter="role == 'groups/123/roles/7920705'"

If you specify the wildcard character for the group ID, you must filter memberships by user (up to 50) in the following format:

• User filter: filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

List Inventory Items

You can filter by collectible status, inventory item type, and inventory item ID. If you don't provide a filter, the user's entire inventory is returned.

The filter format is a semicolon-separated list:

filter={field}={value};{field}={value},{value},...;{field}=...

• {field} can be any of the predefined type fields or ID fields in the following tables.
• {value} can be a string, boolean, or enum. Depending on the field type, this can be a single value (boolean fields) or multiple values (list fields).

Type Fields

ID Fields

Examples

• Returns all collectible items that the user owns:

  filter=onlyCollectibles=true;inventoryItemAssetTypes=*

• Returns all items of the specified types:

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY

• Returns all items of the listed types or any game passes. Excludes badges from the results (the same behavior as if badges wasn't included in the filter):

  filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false

• Returns assets that match the specified IDs:

  filter=assetIds=1,2,3,4

• Returns assets, badges, game passes, and private servers that match the specified IDs:

  filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4

Long Running Operations

Some methods return an Operation object that represents a long-running request that returns an asynchronous response later. The object contains the following fields:

• path - The endpoint path to call to poll for the request's completion. Append the path to the original base URL of the resource method.
• done - A boolean value that represents whether or not the operation has completed.
• response - The response object. This field is empty until the done field has a value of true.
• metadata - Custom metadata specific to the request being made.

Example Operation Object
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}