# Understand the Categories API Effective website navigation often uses mega menus as a fundamental part of the user experience. This is why a robust Content Management System (CMS) is usually the preferred solution. Beyond just offering flexible configurations and support for non-product content like static pages and blogs, CMS provides features like author approval flows, collaborative editing environments, the ability to preview changes, and scheduled publishing. This level of management, often including versioning and role-based permissions, makes a CMS indispensable for professional website operations. However, while a CMS generally offers the most comprehensive and manageable solution, this module explores an alternative approach sometimes employed for specific architectural needs or simpler scenarios: building the data structure for a mega menu directly from your site's [Categories](/api/projects/categories.md). This module concentrates on implementing the necessary backend-for-frontend (BFF) and backend logic. Please note that building the actual user-facing UI components is outside the scope of this lesson. ## Categories in Composable Commerce Categories are a hierarchical structure that you can associate Products to. We’ve explored Categories previously in our [Categorization](/learning-model-your-product-catalog/categorization/overview.md) module. Let’s start by exploring the Categories endpoint in Composable Commerce and the properties you will need to build the mega menu. You will be using the Merchant Center in this section. ### View Categories in the Merchant Center 1. In the Merchant Center’s left navigation, select **Categories** > **Category list** to view the main Categories in your Project. In Composable Commerce, main Categories, also known as top-level Categories, do not have parent Categories. 2. Under the **Subcategories** column, click **>** to view the child Categories (subcategories). 3. Click a row to open the respective Category's information page. Under the **General** tab, you can find the following properties: - **Category name**: the Category's name for each locale available in your project settings. Click **Show all languages** to view all locales, for example: `en-GB`, `en-US`, `de-DE`. This allows you to display localized Category names in your mega menu. - **Category description**: this optional property contains the description of your Category for each locale available in your Project settings. You can use the Category description to display details about the Category, for example, in a tooltip. - **Category order (orderHint)**: assigns an value for ordering Categories. The Category order allows you to use sorting to order your Categories in the mega menu. The Category order should be a value between 0 and 1. Composable Commerce allows you to choose different formats for the `orderHint` value. For example, `0.10` or `.10`. We highly recommend you choose a consistent numbering format across all Categories. - **Custom Fields**: allows you to add data specific to your business needs that are not part of the standard Category object. You can define Custom Fields using [Types](/api/projects/types.md) and then [define the Type](/api/projects/categories.md#set-custom-type) that extends the Category with [Custom Fields](/api/projects/custom-fields.md). Under the **Ext. Search** tab: - **URL slug**: slugs substitute the Category ID in the URL of the Category detail page with a user-friendly and SEO-friendly term. Similar to the Category name, slugs are specified for each locale available in your Project settings. This field's value is unique across Categories and may only contain between 2 and 256 alphanumeric characters, underscores, or hyphens (no white space or special characters like `ñ`, `ü`, `#`, `%`). ## Explore the HTTP API Playground in the Merchant Center Now that you are familiar with the Category properties, let’s explore how those properties are displayed in the response when querying Categories from the Composable Commerce REST API. For this section, we will be using the [HTTP API Playground](/merchant-center/developer-settings.md#api-playgrounds) in the Merchant Center for simplicity. Alternatively, you can use a client like [Postman](https://www.postman.com/) to execute your requests. 1. In the Merchant Center, select **Settings** > **Developer Settings** from the left navigation menu. 2. Select the **HTTP API Playground** tab. 3. Under the **Request method**, choose **GET**. 4. Select **Categories** from the **Endpoint** dropdown menu. 5. Select **Query categories** from the Command dropdown menu. 6. Set the **limit** to 1 to retrieve a single Category. 7. Click **Send**. You will get a response similar to the following: ```json { "limit": 1, "offset": 0, "count": 1, "total": 30, "results": [ { "id": "408ee54b-0f65-49ab-94aa-720928b68f82", "version": 1, "createdAt": "2025-01-20T14:07:16.998Z", "lastModifiedAt": "2025-01-20T14:07:16.998Z", "lastModifiedBy": { "isPlatformClient": true }, "createdBy": { "isPlatformClient": true }, "key": "serving-platters", "name": { "en-GB": "Serving Platters", "en-US": "Serving Platters", "de-DE": "Servierplatten" }, "slug": { "en-GB": "serving-platters", "en-US": "serving-platters", "de-DE": "serving-platters" }, "ancestors": [ { "typeId": "category", "id": "600c67f0-c42b-4e1b-bef2-b8785d0bfbc4" }, { "typeId": "category", "id": "a15f6f32-3388-41a9-8e29-9cc51c1a8286" } ], "parent": { "typeId": "category", "id": "a15f6f32-3388-41a9-8e29-9cc51c1a8286" }, "orderHint": ".0004", "assets": [] } ] } ``` The response JSON above has the following properties: - `limit`: this is the limit specified in the query. Defaults to `20` if not specified. - `offset`: offset used for pagination. While the API allows for using offsets for pagination, using offsets is not recommended with large datasets as they come with a performance penalty. We’ll discuss performance considerations later in this module. - `count`: the number of results or Categories returned by the query. The count will always be lower or equal to the limit. - `total`: the total number of results, or Categories, in Composable Commerce that match the query. - `results`: an array containing the result Categories. Now let’s examine the relevant properties of the Categories returned in the results array that will be used to build the mega menu: - `id`: the system generated ID of the Category. This is an immutable and unique value across all Categories in your Project. - `createdAt`: the ISO 8601 timestamp set when the Category was created. - `key`: the key is a user-defined, human-readable identifier for the Category. This is a mutable field that can be changed at any point. - `name`: an object containing the localized name of the Category. The name object uses the locale, for example `en-GB`, as the key and the localized string as the value. The Category name is not unique across Categories; that is, multiple Categories can have the same name. - `slug`: an object containing the localized name of the URL slug to be used for the Category. The slug object uses the locale as the key and the localized string as the value. The slug value is unique across categories but can be repeated on the locales within the Category. For example, a Category can have the same slug value for `en-US` and `en-GB`. - `ancestors`: an array containing objects representing the parent Categories for this Category, all the way to the top-level Category. The object contains a `typeId`, which will always be `category`, and the parent Category's `id`. - `parent`: an object representing the parent Category. If empty, this means that the Category is a top-level or main Category. - `orderHint`: this is the Category order and is unique across all Categories that share the same parent. `orderHint` is used to control the order the child Categories will be presented in navigation. As you can see, the response has fields that will not be used to build the mega menu. Let’s explore how to use the GraphQL API as a way to get only the properties needed to build the mega menu to reduce over fetching. ## GraphQL Explorer in the Merchant Center The [GraphQL Explorer](/merchant-center/developer-settings.md#graphql-explorer) in the Merchant Center allows you to make calls to the Composable Commerce GraphQL API. We have more information [here](/learning-composable-commerce-developer-essentials/graphql/use-graphiql-and-the-sdk.md) if you need to investigate further how to use the explorer. 1. In the Merchant Center, select **Settings** > **Developer Settings** from the left navigation menu. 2. Choose the **GraphQL Explorer** tab. 3. In the query text, paste the following GraphQL query to get the fields required to build the mega menu. ```graphql query GetCategories { categories(limit: 1, offset: 0, sort: "orderHint") { offset total results { id key orderHint parentRef { id } nameAllLocales { locale value } slugAllLocales { locale value } } count } } ``` 4. Click the **Execute query** button or press **Ctrl+Enter**. You will get a result similar to the following: ```json { "data": { "categories": { "offset": 0, "total": 30, "results": [ { "id": "408ee54b-0f65-49ab-94aa-720928b68f82", "key": "serving-platters", "orderHint": ".0004", "parentRef": { "id": "a15f6f32-3388-41a9-8e29-9cc51c1a8286" }, "nameAllLocales": [ { "locale": "en-GB", "value": "Serving Platters" }, { "locale": "en-US", "value": "Serving Platters" }, { "locale": "de-DE", "value": "Servierplatten" } ], "slugAllLocales": [ { "locale": "en-GB", "value": "serving-platters" }, { "locale": "en-US", "value": "serving-platters" }, { "locale": "de-DE", "value": "serving-platters" } ] } ] } } } ``` By using the GraphQL API, you were able to only query the fields required to build the mega menu. This allows for a more efficient use of memory when you build the mega menu in your code. ## Related pages - [Area overview page with navigation](/learning-implement-product-discovery-and-presentation.md) - [Previous page: Overview](/learning-implement-product-discovery-and-presentation/category-queries-best-practices/overview.md) - [Next page: Build a navigation menu using the SDK](/learning-implement-product-discovery-and-presentation/category-queries-best-practices/build-a-navigation-menu-using-the-sdk.md)