Merge pull request #4348 from braze-inc/CO-890-update-catalogs-api-do…

…cumentation CO-890 Updates the catalogs API documentation
braze-inc · Nov 8, 2022 · 129fd84 · 129fd84
2 parents b954d93 + 701edfe
commit 129fd84
Show file tree

Hide file tree

Showing 18 changed files with 815 additions and 498 deletions.
diff --git a/_docs/_api/endpoints/catalogs.md b/_docs/_api/endpoints/catalogs.md
@@ -9,18 +9,18 @@ description: "This landing page lists the Braze Catalogs Endpoints."
 page_type: landing
 
 guide_top_header: "Catalogs Endpoints"
-guide_top_text: "Use the Braze Catalogs Endpoints to add, edit, and manage your catalogs and catalog item details. You can use the synchronous catalog endpoints to make bulk changes to your catalog. To receive a confirmation that a change to your catalog has been received and processed, use the asynchronous or synchronous catalog item endpoints. <br><br> Looking for guidance on creating a catalog? Check out our article for <a href='/docs/user_guide/personalization_and_dynamic_content/catalog/'>creating and using catalogs</a>."
+guide_top_text: "Use the Braze Catalogs Endpoints to add, edit, and manage your catalogs and catalog item details. You can use the asynchronous catalog endpoints to make bulk changes to your catalog. <br><br> Looking for guidance on creating a catalog? Check out our article for <a href='/docs/user_guide/personalization_and_dynamic_content/catalog/'>creating and using catalogs</a>."
 
-guide_featured_title: "Catalogs Endpoints<br><br>"
+guide_featured_title: "Catalog Management Endpoints<br><br>"
 guide_featured_list:
   - name: "DELETE: Delete Catalog"
-    link: /docs/api/endpoints/catalogs/catalogs/synchronous/delete_catalog/
+    link: /docs/api/endpoints/catalogs/catalog_management/synchronous/delete_catalog/
     fa_icon: fas fa-pen-square
   - name: "GET: List Catalogs"
-    link: /docs/api/endpoints/catalogs/catalogs/synchronous/get_list_catalogs/
+    link: /docs/api/endpoints/catalogs/catalog_management/synchronous/get_list_catalogs/
     fa_icon: fas fa-list-ul
   - name: "POST: Create Catalog"
-    link: /docs/api/endpoints/catalogs/catalogs/synchronous/post_create_catalog/
+    link: /docs/api/endpoints/catalogs/catalog_management/synchronous/post_create_catalog/
     fa_icon: fas fa-check
 
 optional_guide_menu_title: "Catalog Items Endpoints"

diff --git a/..._api/endpoints/catalogs/catalog_items/asynchronous/delete_catalog_items_bulk.md b/..._api/endpoints/catalogs/catalog_items/asynchronous/delete_catalog_items_bulk.md
@@ -12,10 +12,10 @@ description: "This article outlines details about the Delete Multiple Catalog It
 {% api %}
 # Delete multiple catalog items
 {% apimethod delete %}
-/catalogs/catalog_name/items
+/catalogs/{catalog_name}/items
 {% endapimethod %}
 
-Use this endpoint to delete multiple items in your catalog. Each request can support up to 50 items.
+Use this endpoint to delete multiple items in your catalog. Each request can support up to 50 items. This endpoint is asynchronous.
 
 {% alert important %}
 Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access.
@@ -27,69 +27,80 @@ If you'd like to share your feedback on this endpoint or make a request, contact
 
 This endpoint has a shared rate limit of 100 requests per minute between all asynchronous catalog item endpoints.
 
-## Request body
+## Path parameters
 
-```json
-Content-Type: application/json
-Authorization: Bearer YOUR-REST-API-KEY
-{
-    "items": [ (max of 50 items)
-        {
-            "id": (required, item id)
-        },
-        {
-            "id": (required, item id)
-        },
-    ]
-}
-```
+| Parameter | Required | Data Type | Description |
+|---|---|---|---|
+| `catalog_name` | Required | String | Name of the catalog. |
+{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4}
 
-### Request parameters
+## Request parameters
 
 | Parameter | Required | Data Type | Description |
 |---|---|---|---|
-| `catalog_name`  | Required | String | Name of the imported catalog.|
+| `items` | Required | Array | An array that contains item objects. The item objects should contain an `id` referencing the items Braze should delete. Up to 50 item objects are allowed per request. |
 {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4}
 
 ## Example request
 
 ```
-https://rest.iad-03.braze.com/catalogs/catalog_name/items
+curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \
+--header 'Content-Type: application/json' \
+--header 'Authorization: Bearer YOUR-REST-API-KEY' \
+--data-raw '{
+  "items": [
+    {"id": "restaurant1"},
+    {"id": "restaurant2"},
+    {"id": "restaurant3"}
+  ]
+}'
+```
+
+## Response
+
+There are three status code responses for this endpoint: `202`, `400`, and `404`.
+
+### Example success response
+
+The status code `202` could return the following response body.
+
+```json
+{
+  "message": "success"
+}
 ```
 
-## Example error response 
+### Example error response
+
+The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.
 
 ```json
 {
   "errors": [
     {
-        "id": "invalid-ids",
-        "message": "Item ids can only include letters, numbers, hyphens, and underscores",
-        "parameters": ["id"],
-        "parameter_values": ["item_id"]
-    },
-    {
-        "id": "items-missing-ids",
-        "message": "There are 5 items that do not have ids",
-        "parameters": [],
-        "parameter_values": []
+      "id": "items-missing-ids",
+      "message": "There are 1 item(s) that do not have ids",
+      "parameters": [],
+      "parameter_values": []
     }
-    ]
+  ],
+  "message": "Invalid Request",
 }
 ```
 
 ## Troubleshooting
 
-The following table lists possible returned errors and their associated troubleshooting steps, if applicable.
+The following table lists possible returned errors and their associated troubleshooting steps.
 
 | Error | Troubleshooting |
 | --- | --- |
 | `catalog-not-found` | Check that the catalog name is valid. |
+| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. |
 | `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. |
 | `ids-too-large` | Item IDs can't be more than 250 characters. |
 | `ids-not-unique` | Check that the item IDs are unique in the request. |
-| `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. | 
-| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. |
+| `ids-not-strings` | Item IDs must be of type string. |
+| `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. |
 {: .reset-td-br-1 .reset-td-br-2}
 
 {% endapi %}
diff --git a/.../_api/endpoints/catalogs/catalog_items/asynchronous/patch_catalog_items_bulk.md b/.../_api/endpoints/catalogs/catalog_items/asynchronous/patch_catalog_items_bulk.md
@@ -13,10 +13,10 @@ description: "This article outlines details about the Edit Multiple Catalog Item
 {% api %}
 # Edit multiple catalog items
 {% apimethod patch %}
-/catalogs/catalog_name/items
+/catalogs/{catalog_name}/items
 {% endapimethod %}
 
-Use this endpoint to edit multiple items in your catalog. Each request can support up to 50 items.
+Use this endpoint to edit multiple items in your catalog. Each request can support up to 50 items. This endpoint is asynchronous.
 
 {% alert important %}
 Support for this endpoint is currently in early access. Contact your Braze account manager if you are interested in participating in the early access.
@@ -28,74 +28,76 @@ If you'd like to share your feedback on this endpoint or make a request, contact
 
 This endpoint has a shared rate limit of 100 requests per minute between all asynchronous catalog item endpoints.
 
-## Request body
+## Path parameters
 
-```
-Content-Type: application/json
-Authorization: Bearer YOUR-REST-API-KEY
-```
-
-```json
-{
-    "items": [ (max of 50 items)
-        {
-            "id": (required, item id),
-            "count": (required, item count),
-        },
-        {
-            "id": (required, item id),
-            "count": (required, item count),
-        },
-        {
-            "id": (required, item id),
-            "count": (required, item count),
-        }
-    ]
-}
-```
+| Parameter | Required | Data Type | Description |
+|---|---|---|---|
+| `catalog_name` | Required | String | Name of the catalog. |
+{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4}
 
-### Request parameters
+## Request parameters
 
 | Parameter | Required | Data Type | Description |
 |---|---|---|---|
-| `item_id`  | Required | String | Item ID for a catalog item. |
+| `items` | Required | Array | An array that contains item objects. The item objects should contain fields that exist in the catalog. Up to 50 item objects are allowed per request. |
 {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4}
 
 ## Example request
+
 ```
-curl --location --request PATCH 'https://rest.iad-01.braze.com/catalogs/catalog_name/items' \
+curl --location --request PATCH 'https://rest.iad-03.braze.com/catalogs/restaurants/items' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer YOUR-REST-API-KEY' \
 --data-raw '{
-    "items": [
-        {
-            "id": "item_0",
-            "count": 1,
-        },
-        {
-            "id": "item_1",
-            "count": 2,
-        },
-        {
-            "id": "item_2",
-            "count": 3,
-        }
-    ]
+  "items": [
+    {
+      "id": "restaurant1",
+      "Name": "Restaurant",
+      "Loyalty_Program": false,
+      "Open_Time": "2021-09-03T09:03:19.967+00:00"
+    },
+    {
+      "id": "restaurant3",
+      "City": "San Francisco",
+      "Rating": 2
+    }
+  ]
+}'
+```
+
+## Response
+
+There are three status code responses for this endpoint: `202`, `400`, and `404`.
+
+### Example success response
+
+The status code `202` could return the following response body.
+
+```json
+{
+  "message": "success"
 }
 ```
 
-## Example error response 
+### Example error response
+
+The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.
 
 ```json
 {
   "errors": [
     {
-      "id": "catalog-not-found",
-      "message": "Could not find catalog",
-      "parameters": ["catalog_name"],
-      "parameter_values": ["catalog_name"]
+      "id": "invalid-fields",
+      "message": "Some of the fields given do not exist in the catalog",
+      "parameters": [
+        "id"
+      ],
+      "parameter_values": [
+        "restaurant1"
+      ]
     }
-  ]
+  ],
+  "message": "Invalid Request"
 }
 ```
 
@@ -106,12 +108,14 @@ The following table lists possible returned errors and their associated troubles
 | Error | Troubleshooting |
 | --- | --- |
 | `catalog-not-found` | Check that the catalog name is valid. |
+| `item-array-invalid` | `items` must be an array of objects. |
+| `request-includes-too-many-items` | Your request has too many items. The item limit per request is 50. |
 | `invalid-ids` | Item IDs can only include letters, numbers, hyphens, and underscores. |
 | `ids-too-large` | Item IDs can't be more than 250 characters. |
-| `items-too-large` | Item values can't exceed 5,000 characters. |
 | `ids-not-unique` | Item IDs must be unique in the request. |
-| `request-includes-too-many-items` | Your request has too many items. The maximum is 50. |
+| `ids-not-strings` | Item IDs must be of type string. |
 | `items-missing-ids` | There are items that do not have item IDs. Check that each item has an item ID. |
+| `items-too-large` | Item values can't exceed 5,000 characters. |
 | `invalid-fields` | Confirm that the fields in the request exist in the catalog. |
 | `unable-to-coerce-value` | Item types can't be converted. |
 {: .reset-td-br-1 .reset-td-br-2}