Document some GraphQL changes between 3.3 and 4.x (#2595)

--------- Co-authored-by: Marek Nocoń <mnocon@users.noreply.github.com> (cherry picked from commit f21a29c)
ibexa · Jan 29, 2025 · 9e6fded · 9e6fded
1 parent 8c25bea
commit 9e6fded
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 6 deletions.
diff --git a/docs/api/graphql/graphql_queries.md b/docs/api/graphql/graphql_queries.md
@@ -15,7 +15,7 @@ To get a specific content item by its content ID, location ID, or URL alias, use
 ```
 {
   content {
-    article (contentId: 62) {
+    article(contentId: 62) {
       title
       author {
         name
@@ -52,8 +52,17 @@ The query accepts `locationId`, `remoteId`, and `urlAlias` as arguments.
 
 ```
 {
-  item (locationId: 2) {
+  item(locationId: 2) {
     _name
+    ... on FolderItem {
+        name
+    }
+    ... on LandingPageItem {
+        name
+    }
+    ... on ArticleItem {
+        title
+    }
   }
 }
 ```
@@ -181,9 +190,9 @@ To get the IDs and names of all Fields in the `article` content type:
 {
   content {
     _types {
-      article{
+      article {
         _info {
-          fieldDefinitions{
+          fieldDefinitions {
             id
             name
           }
@@ -318,8 +327,8 @@ Alternatively, you can query the `children` property of an `item` or `content` o
 
 ```
 {
-  item (locationId: 2) {
-    _location{
+  item(locationId: 2) {
+    _location {
       children {
         edges {
           node {

diff --git a/docs/css/custom.css b/docs/css/custom.css
@@ -379,6 +379,10 @@ ul li li li {
     background-color: var(--table-header);
 }
 
+.md-typeset table td.compare {
+    border: 0.05rem solid var(--md-typeset-table-color)
+}
+
 .md-nav__link[data-md-state=blur] {
     color: rgb(19, 28, 38);
 }

diff --git a/docs/update_and_migration/from_3.3/to_4.0.md b/docs/update_and_migration/from_3.3/to_4.0.md
@@ -168,6 +168,56 @@ php bin/console ibexa:migrations:migrate
 
 ## Update your custom code
 
+### GraphQL
+
+Some GraphQL names have changed. Adapt your queries according to the table below.
+
+| 3.3 name                                          | 4.0 name                                    |
+|:--------------------------------------------------|:--------------------------------------------|
+| `id` argument                                     | `contentId` argument                        |
+| `_info` content item property                     | `_contentInfo` content item property        |
+| `<ContentType>Content` (example: `FolderContent`) | `<ContentType>Item` (example: `FolderItem`) |
+
+Example of an updated query:
+
+<table>
+<thead><tr><th scope="col">3.3</th><th scope="col">4.0</th></tr></thead>
+<tbody>
+<tr><td class="compare">
+```graphql
+{
+  content {
+    folder(id: 1) {
+      _info {
+        id
+        name
+      }
+    }
+  }
+}
+```
+</td><td class="compare">
+```graphql
+{
+  content {
+    folder(contentId: 1) {
+       _contentInfo{
+        id
+        name
+      }
+    }
+  }
+}
+```
+</td></tr>
+</tbody></table>
+
+Notice that the argument have been updated to `contentId` while the `id` property keeps its name.
+
+While revisiting GraphQL queries, you may consider the new feature `item`
+allowing to fetch a content item without knowing its content type.
+For more information, see [Get a content item](graphql_queries.md#get-a-content-item).
+
 ### Back office customization
 
 The v4 version of [[= product_name =]] is using Bootstrap 5 in the back office. If you were using Bootstrap 4 for styling, you need to update and adjust all custom back office components [following the migration guide from Bootstrap 4](https://getbootstrap.com/docs/5.0/migration/).