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.

Categories in Composable Commerce

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.

• 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.

• 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 and then define the Type that extends the Category with Custom Fields.

• 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.

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:

{
  "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

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.

query GetCategories {
  categories(limit: 1, offset: 0, sort: "orderHint") {
    offset
    total
    results {
      id
      key
      orderHint
      parentRef {
        id
      }
      nameAllLocales {
        locale
        value
      }
      slugAllLocales {
        locale
        value
      }
    }
    count
  }
}

1. Click the Execute query button or press Ctrl+Enter.

You will get a result similar to the following:

{
  "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.

Test your knowledge