From 8cc4705eba90293fc968b1c73fa6cd629a23aa3e Mon Sep 17 00:00:00 2001 From: bc-andreadao <96258747+bc-andreadao@users.noreply.github.com> Date: Tue, 16 Jan 2024 09:04:38 -0800 Subject: [PATCH] DEVDOCS-5575 [update]: Catalog API, categories (#18) Co-authored-by: Sarah Riehl --- .../deprecations-and-sunsets.mdx | 5 ++- .../v2-catalog-products/v2-categories.mdx | 2 +- reference/catalog/categories_catalog.v3.yml | 41 +++++++++++++------ .../catalog/category-trees_catalog.v3.yml | 4 +- 4 files changed, 35 insertions(+), 17 deletions(-) diff --git a/docs/api-docs/getting-started/deprecations-and-sunsets.mdx b/docs/api-docs/getting-started/deprecations-and-sunsets.mdx index 73b1e575c..63b34740f 100644 --- a/docs/api-docs/getting-started/deprecations-and-sunsets.mdx +++ b/docs/api-docs/getting-started/deprecations-and-sunsets.mdx @@ -9,13 +9,14 @@ This article provides a reference for deprecated APIs and exposes BigCommerce's ## Deprecations -The following APIs, features, and tools are deprecated. We discourage using these listed items, as BigCommerce no longer supports them. Instead, consider using the suggested replacements. +The following APIs, features, and tools are deprecated. We discourage using these listed items, as BigCommerce either no longer supports them or won't be providing additional support or new features. Instead, consider using the suggested replacements. | Deprecated API or feature | Replacement | |:--------------------------|:------------| | `/v2/brands` | [Catalog V3 Brands](/docs/rest-catalog/brands#get-all-brands) | | `/v3/content/widgets/search` | [Widgets V3, Get all widgets](/docs/rest-content/widgets/widget#get-all-widgets) | -| `/v2/categories` | [Catalog V3 Categories](/docs/rest-catalog/categories#get-all-categories) | +| `/v2/categories` | [Catalog V3 Catalog Trees - Categories](/docs/rest-catalog/category-trees/categories#get-all-categories) | +| `/v3/catalog/categories` | [Catalog V3 Catalog Trees - Categories](/docs/rest-catalog/category-trees/categories#get-all-categories) | | `/v2/customers` | [Customers V3](/docs/rest-management/customers) | | `/v3/hooks/events`| [Get Events](/docs/webhooks/webhooks/webhook-events#get-events) | | `/v2/options` | [Catalog V3 Product Modifiers](/docs/rest-catalog/product-modifiers#get-all-product-modifiers), [Catalog V3 Product Variant Options](/docs/rest-catalog/product-variant-options#get-all-product-variant-options). See the [Accessing product options](#accessing-product-options-with-V3) callout. | diff --git a/docs/legacy/v2-catalog-products/v2-categories.mdx b/docs/legacy/v2-catalog-products/v2-categories.mdx index 046dc6466..1396337e7 100644 --- a/docs/legacy/v2-catalog-products/v2-categories.mdx +++ b/docs/legacy/v2-catalog-products/v2-categories.mdx @@ -12,7 +12,7 @@ Index of hierarchical categories used to organize and group products. #### Deprecated Avoid using this API operation if possible. It will be removed in a future version. - For the most up-to-date version of this API, see [Category](/docs/rest-catalog/categories). + For the most up-to-date version of this API, see [Catalog V3 Catalog Trees - Categories](/docs/rest-catalog/category-trees/categories). ### Category Object – Properties diff --git a/reference/catalog/categories_catalog.v3.yml b/reference/catalog/categories_catalog.v3.yml index f8bf8c387..96b4cfc81 100644 --- a/reference/catalog/categories_catalog.v3.yml +++ b/reference/catalog/categories_catalog.v3.yml @@ -2,9 +2,12 @@ openapi: '3.0.3' info: title: Catalog - Categories description: |- + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). - - Our Catalog Categories endpoints let you [create individual categories](/docs/rest-catalog/categories#create-a-category) and [modify categories](/docs/rest-catalog/categories#update-a-category) that organize a store's products, as well as [delete categories](/docs/rest-catalog/categories#delete-a-category). + + > Warning: + > - The [Catalog V3 Categories](/docs/rest-catalog/categories) endpoints were primarily useful in applications for single storefront stores and are deprecated. We still support these endpoints, but will not implement new features within them. The endpoints will continue working as is. + > - To manage Categories, use the [Catalog V3 Category Trees - Categories](/docs/rest-catalog/category-trees/categories) endpoints. These endpoints work for both [MSF-enabled stores](/docs/storefront/multi-storefront) and single storefront stores, and are backwards-compatible with categories created using Catalog V3 Categories. Category images have their own dedicated [create a category image](/docs/rest-catalog/categories/images#create-a-category-image) and [delete a category image](/docs/rest-catalog/categories/images#delete-a-category-image) endpoints. @@ -12,8 +15,6 @@ info: This API family also contains endpoints to [update product sort order](/docs/rest-catalog/categories/sort-order#update-product-sort-order) within a category. - These endpoints are primarily useful in applications for single storefront stores. To work with categories for an [MSF-enabled store](/docs/storefront/multi-storefront), see [Category Trees](/docs/rest-catalog/category-trees). - > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. ## Resources @@ -45,17 +46,20 @@ servers: security: - X-Auth-Token: [] tags: - - name: Categories - name: Metafields - name: Images - name: Sort Order + - name: Categories (deprecated) paths: '/catalog/categories': get: tags: - - Categories + - Categories (deprecated) + deprecated: true summary: Get All Categories description: |- + When possible, use the [Catalog Trees - Get all categories](/docs/rest-catalog/category-trees/categories#get-all-categories) endpoint instead. + Returns a list of *Categories*. Optional filter parameters can be passed in. **Note:** @@ -367,9 +371,10 @@ paths: current: '?page=1&limit=50' post: tags: - - Categories + - Categories (deprecated) + deprecated: true summary: Create a Category - description: "Creates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create Categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit.\n\n **Note:**\n The default rate limit for this endpoint is 40 concurrent requests.\n" + description: "When possible, use the [Category Trees - Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint instead.\n\nCreates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit.\n\n **Note:**\n The default rate limit for this endpoint is 40 concurrent requests.\n" operationId: createCategory parameters: - $ref: '#/components/parameters/ContentType' @@ -573,9 +578,12 @@ paths: x-codegen-request-body-name: category delete: tags: - - Categories + - Categories (deprecated) + deprecated: true summary: Delete Categories description: |- + When possible, use the [Category Trees - Delete categories](/docs/rest-catalog/category-trees/categories#delete-categories) endpoint instead. + Deletes *Category* objects. At least one filter parameter is required to perform the `DELETE` operation. **Usage Notes** @@ -729,9 +737,12 @@ paths: '/catalog/categories/{category_id}': get: tags: - - Categories + - Categories (deprecated) + deprecated: true summary: Get a Category description: |- + When possible, use the [Catalog Trees - Get all categories](/docs/rest-catalog/category-trees/categories#get-all-categories) endpoint instead. You can provide a category identifier using query parameters to retrieve a single category. + Returns a single *Category*. Optional parameters can be passed in. **Note:** @@ -784,9 +795,12 @@ paths: description: Error payload for the BigCommerce API. put: tags: - - Categories + - Categories (deprecated) + deprecated: true summary: Update a Category description: |- + When possible, use the [Catalog Trees - Update categories](/docs/rest-catalog/category-trees/categories#update-categories) endpoint instead. + Updates a *Category*. **Required Fields** @@ -1148,9 +1162,12 @@ paths: x-codegen-request-body-name: category delete: tags: - - Categories + - Categories (deprecated) + deprecated: true summary: Delete a Category description: |- + When possible, use the [Category Trees - Delete categories](/docs/rest-catalog/category-trees/categories#delete-categories) endpoint instead. You can provide a category identifier using query parameters to delete a single category. + Deletes a *Category*. **Note:** diff --git a/reference/catalog/category-trees_catalog.v3.yml b/reference/catalog/category-trees_catalog.v3.yml index 0f4ef0881..a271f74aa 100644 --- a/reference/catalog/category-trees_catalog.v3.yml +++ b/reference/catalog/category-trees_catalog.v3.yml @@ -4,7 +4,7 @@ info: description: |- > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). - Our Catalog Category Trees endpoints are the more modern and performant counterparts to the [Categories endpoints](/docs/rest-catalog/categories). Although the Category Trees endpoints and objects are designed to center an MSF-compatible, [multi-tenant category tree architecture](#categories), the endpoints work just as well in a single storefront context. + Our Catalog Category Trees and their [Categories](/docs/rest-catalog/category-trees/categories) endpoints are the more modern and performant counterparts to the [Categories (deprecated)](/docs/rest-catalog/categories) endpoints. Although the Category Trees endpoints and objects are designed to center an MSF-compatible, [multi-tenant category tree architecture](#categories), the endpoints work just as well in a single storefront context and support batch requests. Use [Catalog Trees Categories](/docs/rest-catalog/category-trees/categories) endpoints, instead of [Categories (deprecated)](/docs/rest-catalog/categories) endpoints. The Category Trees endpoints let you [get the Categories for a specific tree](/docs/rest-catalog/category-trees/categories#get-a-category-tree), and [bulk create](/docs/rest-catalog/category-trees/categories#create-categories), [bulk update](/docs/rest-catalog/category-trees/categories#update-categories), and [bulk delete](/docs/rest-catalog/category-trees/categories#delete-categories) Categories. You can also [bulk update the properties of Category Trees](/docs/rest-catalog/category-trees#upsert-category-trees), which includes changing the channels to which a Tree is assigned. @@ -515,7 +515,7 @@ paths: additionalProp2: string additionalProp3: string tags: - - Categories + - Category Trees parameters: - $ref: '#/components/parameters/Accept' - schema: