SDK: Refactor page.get() to Always Use GraphQL with Stable Response

[rjvelazco]

Background

dotClient.page.get() switches between the Page REST API and GraphQL depending on the incoming params.
This causes two key pain points:

• Unpredictable response shapes – the same call can return different keys/types.
• Debug & performance overhead – engineers must inspect which endpoint fired, slowing troubleshooting and tuning.

For clarity and future‑proofing, we’ll route every page.get() call through GraphQL and return one stable object shape.

Task

Refactor dotClient.page.get() to always use GraphQL, no matter what params are passed. The method must consistently return to the same typed object:

const { pageAsset, navigation,  content, params } = response;

Note:
The params object is the same that the method receive.

Proposed Objective

Same as Parent Issue

Proposed Priority

Priority 2 - Important

Acceptance Criteria

Acceptance Criteria

• GraphQL only : every fecth should hit our graphql endpoint
• Stable response : method always returns the same object.
• Generic flexibility : dev can supply their own generics: <PageAssetBase<T>, PageAssetBase<T>, TContent> to override the default types.
• Extensible bases: expose interfaces PageAssetBase<T> and PageAssetBase<T> that consumers can extend.
• Cleanup unused code: Remove all the code related to the page API.
• Documentation updated: Mark it as a breaking change for those who were expecting the object to be like this:
  const page = reponse

Pseudo-code:

async function getPage () {
  const params = {
    graphql: {
     page: ``,
      navigation: `navigation(path: '/', depth: 1) {
        title,
        href,
      }`,
      content: {
        blog: `blogCollection('+contentType:BlogPosting') {
          inode,
          title,
          body,
          contentType,
          publishDate,
          tags,
          categories,
        }`
      }
    }
  }

  const response = await dotcms.page.getStable("/api/v1/content/title/test", params)

  return response
}

[fmontes]

@rjvelazco how to we pass the parameters that the page api support? lang, mode, etc...

[rjvelazco]

@fmontes We follow the GraphQL variables pattern and include the variable in the same request as the query

[fmontes]

@rjvelazco write me an example here please.

[rjvelazco]

The user calls dotcms.page.get

async function getPage() {
  const params = {
    languageId: "1",
    personaId: "2102131231",
    graphql: {
      navigation: `navigation(path: "/", depth: 1) { title }`,
      content: {
        blog: `blogCollection("+contentType:BlogPosting") { title }`
      },
      variables: {
        myCustomVariable
      }
    }
  };

  const response = await dotcms.page.get("/my-test", params);

  return response;
}

What happens under the hood

const getPage = async (options) => {
  const { graphql = {}, ...pageParams } = options;
  const { variables = {}, ...customQueries } = graphql;
   const query = buildQuery(basedPageQuery, customQueries);
  const requestBody = JSON.stringify({
    query,
    variables: {
      ...pageParams,   // languageId, personaId, etc.
      ...variables     // custom GraphQL variables
    }
  });

  return await fetch("/api/v1/graphql", {
        method: 'POST',
        body: requestBody
    });
};

Base query using variables

Our basedPageQuery follows the GraphQL variables pattern:

page(
  url: $url,
  languageId: $languageId,
  pageMode: $mode,
  persona: $personaId,
  fireRules: $fireRules,
  publishDate: $publishDate,
  site: $siteId
) {
  # … fields …
}

We merge both built‑in params and user variables, the GraphQL query automatically receives everything it needs

[rjvelazco]

We also talk about implementing axios, let me create a separated card for that

[rjvelazco]

Axios ticket: #31982