update Open Source Docs from Roblox internal teams

Author: rbx-open-source-docs[bot]

content/common/navigation/cloud/reference.yaml

@@ -27,6 +27,63 @@ navigation:
     path: /cloud/reference/errors
   - title: OpenAPI descriptions
     path: /cloud/reference/openapi
+  - heading: Use Case Reference
+  - title: All features
+    section:
+      - title: Accounts
+        path: /cloud/features/accounts
+      - title: Assets
+        path: /cloud/features/assets
+      - title: Avatars
+        path: /cloud/features/avatars
+      - title: Badges
+        path: /cloud/features/badges
+      - title: Bans and blocks
+        path: /cloud/features/bans-and-blocks
+      - title: Chats
+        path: /cloud/features/chats
+      - title: Creator Store
+        path: /cloud/features/creator-store
+      - title: Developer products
+        path: /cloud/features/developer-products
+      - title: Friends
+        path: /cloud/features/friends
+      - title: Game passes
+        path: /cloud/features/game-passes
+      - title: Groups
+        path: /cloud/features/groups
+      - title: Interactions
+        path: /cloud/features/interactions
+      - title: Inventories
+        path: /cloud/features/inventories
+      - title: Localization
+        path: /cloud/features/localization
+      - title: Luau execution
+        path: /cloud/features/luau-execution
+      - title: Metadata
+        path: /cloud/features/metadata
+      - title: Notifications
+        path: /cloud/features/notifications
+      - title: Places
+        path: /cloud/features/places
+      - title: Private servers
+        path: /cloud/features/private-servers
+      - title: Sponsored campaigns
+        path: /cloud/features/sponsored-campaigns
+      - title: Storage
+        path: /cloud/features/storage
+      - title: Team Create
+        path: /cloud/features/team-create
+      - title: Thumbnails
+        path: /cloud/features/thumbnails
+      - title: Trades
+        path: /cloud/features/trades
+      - title: Universes
+        path: /cloud/features/universes
+      - title: User profiles
+        path: /cloud/features/user-profiles
+      - title: Users
+        path: /cloud/features/users
   - heading: Open Cloud v2
   - title: All Cloud API # doesn't show anywhere
     path: /cloud/reference/
@@ -39,7 +96,6 @@ navigation:
       - name: v1
         path: /reference/cloud/assets/v1
   - title: Data stores
-    path: /reference/cloud/datastores-api/v1
     section:
       - title: Standard data stores
         type: cloudapi
@@ -65,7 +121,6 @@ navigation:
   - title: Overview
     path: /cloud/legacy
   - title: Accounts
-    path: /cloud/legacy/accountinformation/v1
     section:
       - title: Account information
         type: cloudlegacy
@@ -97,14 +152,19 @@ navigation:
         versions:
           - name: v1
             path: /cloud/legacy/auth/v1
+      - title: Private messages
+        type: cloudlegacy
+        ignoreTranslation: true
+        versions:
+          - name: v1
+            path: /cloud/legacy/privatemessages/v1
       - title: Two-step verification
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
             path: /cloud/legacy/twostepverification/v1
   - title: Assets
-    path: /cloud/legacy/assetdelivery/v2
     section:
       - title: Asset delivery v2
         type: cloudlegacy
@@ -143,7 +203,6 @@ navigation:
           - name: v1
             path: /cloud/legacy/publish/v1
   - title: Avatar
-    path: /cloud/legacy/avatar/v3
     section:
       - title: Avatar v3
         type: cloudlegacy
@@ -164,7 +223,6 @@ navigation:
           - name: v1
             path: /cloud/legacy/avatar/v1
   - title: Localization
-    path: /cloud/legacy/economy/v1
     section:
       - title: Economy
         type: cloudlegacy
@@ -203,7 +261,6 @@ navigation:
           - name: v1
             path: /cloud/legacy/translationroles/v1
   - title: Metadata
-    path: /cloud/legacy/clientsettings/v2
     section:
       - title: Client settings v2
         type: cloudlegacy
@@ -218,7 +275,6 @@ navigation:
           - name: v1
             path: /cloud/legacy/clientsettings/v1
   - title: Thumbnails
-    path: /cloud/legacy/thumbnails/v1
     section:
       - title: Thumbnails
         type: cloudlegacy
@@ -238,144 +294,136 @@ navigation:
         versions:
           - name: v1
             path: /cloud/legacy/metrics/v1
-  - title: Users and groups
-    path: /cloud/legacy/contacts/v1
+  - title: Universes
     section:
-      - title: Contacts
+      - title: Badges
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/contacts/v1
-      - title: Followings v2
+            path: /cloud/legacy/badges/v1
+      - title: Chat
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v2
-            path: /cloud/legacy/followings/v2
-      - title: Followings v1
+            path: /cloud/legacy/chat/v2
+      - title: Develop v2
         type: cloudlegacy
         ignoreTranslation: true
         versions:
-          - name: v1
-            path: /cloud/legacy/followings/v1
-      - title: Friends
+          - name: v2
+            path: /cloud/legacy/develop/v2
+      - title: Develop v1
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/friends/v1
-      - title: Groups v2
-        type: cloudlegacy
-        ignoreTranslation: true
-        versions:
-          - name: v2
-            path: /cloud/legacy/groups/v2
-      - title: Groups v1
+            path: /cloud/legacy/develop/v1
+      - title: Economy creator stats
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/groups/v1
-      - title: Inventory v2
+            path: /cloud/legacy/economycreatorstats/v1
+      - title: Engagement payouts
         type: cloudlegacy
         ignoreTranslation: true
         versions:
-          - name: v2
-            path: /cloud/legacy/inventory/v2
-      - title: Inventory v1
+          - name: v1
+            path: /cloud/legacy/engagementpayouts/v1
+      - title: Game join
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/inventory/v1
-      - title: Presence
+            path: /cloud/legacy/gamejoin/v1
+      - title: Games v2
         type: cloudlegacy
         ignoreTranslation: true
         versions:
-          - name: v1
-            path: /cloud/legacy/presence/v1
-      - title: Users
+          - name: v2
+            path: /cloud/legacy/games/v2
+      - title: Games v1
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/users/v1
-      - title: Premium features
+            path: /cloud/legacy/games/v1
+  - title: Users and groups
+    section:
+      - title: Contacts
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/premiumfeatures/v1
-      - title: Private messages
+            path: /cloud/legacy/contacts/v1
+      - title: Followings v2
         type: cloudlegacy
         ignoreTranslation: true
         versions:
-          - name: v1
-            path: /cloud/legacy/privatemessages/v1
-      - title: Trades
+          - name: v2
+            path: /cloud/legacy/followings/v2
+      - title: Followings v1
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/trades/v1
-  - title: Universes
-    path: /cloud/legacy/badges/v1
-    section:
-      - title: Badges
+            path: /cloud/legacy/followings/v1
+      - title: Friends
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/badges/v1
-      - title: Chat
+            path: /cloud/legacy/friends/v1
+      - title: Groups v2
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v2
-            path: /cloud/legacy/chat/v2
-      - title: Develop v2
+            path: /cloud/legacy/groups/v2
+      - title: Groups v1
         type: cloudlegacy
         ignoreTranslation: true
         versions:
-          - name: v2
-            path: /cloud/legacy/develop/v2
-      - title: Develop v1
+          - name: v1
+            path: /cloud/legacy/groups/v1
+      - title: Inventory v2
         type: cloudlegacy
         ignoreTranslation: true
         versions:
-          - name: v1
-            path: /cloud/legacy/develop/v1
-      - title: Economy creator stats
+          - name: v2
+            path: /cloud/legacy/inventory/v2
+      - title: Inventory v1
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/economycreatorstats/v1
-      - title: Engagement payouts
+            path: /cloud/legacy/inventory/v1
+      - title: Presence
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/engagementpayouts/v1
-      - title: Game join
+            path: /cloud/legacy/presence/v1
+      - title: Users
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/gamejoin/v1
-      - title: Games v2
+            path: /cloud/legacy/users/v1
+      - title: Premium features
         type: cloudlegacy
         ignoreTranslation: true
         versions:
-          - name: v2
-            path: /cloud/legacy/games/v2
-      - title: Games v1
+          - name: v1
+            path: /cloud/legacy/premiumfeatures/v1
+      - title: Trades
         type: cloudlegacy
         ignoreTranslation: true
         versions:
           - name: v1
-            path: /cloud/legacy/games/v1
+            path: /cloud/legacy/trades/v1
   - title: Ad configuration
     type: cloudlegacy
     ignoreTranslation: true

content/en-us/cloud/index.md

@@ -14,9 +14,9 @@ Roblox has four categories of HTTP REST API:
 - [Legacy with API key and/or OAuth 2.0 authentication](legacy.md)
 - [Legacy with cookie authentication](legacy.md)
 
-Whenever possible, use the Open Cloud v2 API. This API has the strongest stability guarantees and regularly adds new resources. The Open Cloud v1 API also has strong stability guarantees, but a more limited set of resources.
+Whenever possible, use Open Cloud v2, Open Cloud v1, or legacy endpoints that support API key and/or OAuth 2.0 authentication. These APIs have strong stability guarantees and regularly add new resources.
 
-The legacy APIs, no matter which types of authentication they support, can incorporate breaking changes without notice and have minimal stability guarantees. They are not part of the Open Cloud v2 or v1 APIs, and we don't recommend them for production applications.
+Legacy API endpoints with cookie authentication can incorporate breaking changes without notice and have minimal stability guarantees. We don't recommend them for production applications.
 
 <Alert severity="info">
 Roblox also offers [webhooks](./webhooks/webhook-notifications.md), which can notify your applications when certain events occur, such as refunds or changes to subscriptions.

content/en-us/cloud/legacy.md

@@ -5,11 +5,9 @@ description: Lists legacy REST APIs for Open Cloud.
 
 This section contains documentation for Roblox's legacy REST APIs.
 
-- Roblox offers API key and/or OAuth 2.0 support **for the select legacy API endpoints listed on this page**. See the tables below for the list of available operations and authentication types.
+- Roblox offers API key and/or OAuth 2.0 support **for the select legacy API endpoints listed on this page**. These endpoints have the same stability guarantees as the Open Cloud v2 and v1 APIs. See the tables below for the list of available operations and authentication types.
 
-- All other legacy API endpoints use cookie-based authentication. We do not recommend depending on these APIs, as they rely on sharing cookies with application code.
-
-- All legacy APIs, regardless of authentication type, can change without notice and do not have the stability guarantees of the Open Cloud APIs. See the left navigation for the full list of legacy API endpoints.
+- All other legacy API endpoints use cookie-based authentication. We do not recommend depending on these APIs, as they can incorporate breaking changes without notice and rely on sharing cookies with application code.
 
 ## Badges API
 

content/en-us/includes/cloud/legacy-warning.md

@@ -0,0 +1,7 @@
+---
+title: Legacy API warning
+---
+
+<Alert severity="warning">
+Legacy APIs with cookie authentication can incorporate breaking changes without notice. We don't recommend them for production applications.
+</Alert>

content/en-us/reference/cloud/assets/v1.json

@@ -269,7 +269,7 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/Operation",
-                  "example": "{\\\"previews\\\": [\\n    {\\\"asset\\\": \\\"assets/123\\\", \\\"altText\\\": \\\"preview 1\\\"},\\n    {\\\"asset\\\": \\\"assets/456\\\", \\\"altText\\\": \\\"preview 2\\\"}\\n]}"
+                  "example": "{\"previews\": [\n  {\"asset\": \"assets/123\", \"altText\": \"preview 1\"},\n  {\"asset\": \"assets/456\", \"altText\": \"preview 2\"}\n]}"
                 }
               }
             }