docs: Correct GraphQL mutation capabilities and add official guidance section

- Correct misconception that GraphQL cannot create/modify content
- Add GraphQL mutation examples (createPage, updatePage, deletePage)
- Add Official Guidance section documenting lack of explicit Atlassian guidance
- Add practical considerations for choosing between GraphQL and REST APIs
- Document beta status and performance considerations from community discussions

Author: codekiln

pages/Atlassian___Confluence___API___Concept___GraphQL vs REST.md

@@ -13,6 +13,7 @@ tags:: [[Diataxis/Explanation]]
 	- ## Key Principles
 		- **Query Efficiency**: GraphQL enables fetching multiple related resources in a single request, while REST typically requires multiple endpoint calls
 		- **Data Control**: GraphQL clients specify exactly what fields they need, reducing over-fetching of unnecessary data
+		- **Write Operations**: Both APIs support CRUD operations, but with different approaches. GraphQL provides mutations like `createPage`, `updatePage`, and `deletePage` for content management. REST provides comprehensive endpoints including dedicated operations like copying pages (`POST /wiki/rest/api/content/{id}/copy`) that don't have direct GraphQL equivalents
 		- **Schema Evolution**: GraphQL uses continuous schema evolution with beta fields and deprecation periods, while REST relies on explicit versioning (v1, v2)
 		- **Flexibility vs Stability**: REST provides stable, versioned endpoints with predictable behavior, while GraphQL offers flexibility but may change more frequently
 		- **Tooling Maturity**: REST benefits from extensive tooling and community support, while GraphQL provides newer tools like GraphQL Explorer for query discovery
@@ -24,8 +25,9 @@ tags:: [[Diataxis/Explanation]]
 			- Versioning handled through URL paths (`/api/v1/`, `/api/v2/`)
 			- Authentication via OAuth 2.0 or Basic auth
 		- **GraphQL API Approach**:
-			- Single endpoint for all queries (typically `/graphql`)
+			- Single endpoint for all queries and mutations (typically `/graphql`)
 			- Clients send queries specifying exact fields and relationships needed
+			- Mutations available for creating, updating, and deleting content (e.g., `createPage`, `updatePage`, `deletePage`)
 			- Query language allows nested data fetching in one request
 			- Schema introspection enables self-documenting APIs
 			- Authentication via OAuth 2.0 or JWT for cloud apps
@@ -48,11 +50,51 @@ tags:: [[Diataxis/Explanation]]
 			}
 			~~~
 			- Result: One request fetching only the specified fields
+		- **GraphQL Mutation Example**: Creating a new page:
+			~~~
+			mutation {
+			  confluence {
+			    createPage(input: {
+			      spaceId: "123"
+			      title: "New Page"
+			      body: {storage: {value: "Content here", representation: STORAGE}}
+			    }) {
+			      page {
+			        id
+			        title
+			      }
+			    }
+			  }
+			}
+			~~~
+			- Result: Single mutation request to create and return the new page
+		- **Duplicating Pages**: While both APIs can duplicate pages, REST provides a dedicated copy endpoint (`POST /wiki/rest/api/content/{id}/copy`), while GraphQL requires fetching the original page content via query, then creating a new page via mutation
 		- **Performance Trade-off**: While GraphQL can reduce request count, it may take longer for complex queries compared to optimized REST v2 endpoints in some scenarios
+	- ## Official Guidance
+		- **Atlassian has not provided explicit, comprehensive guidance** on when to choose GraphQL vs REST APIs for Confluence
+		- Documentation focuses on describing capabilities rather than prescribing when to use each API
+		- Developers must evaluate both APIs based on their specific use cases and requirements
+		- **Considerations for Choosing**:
+			- **Use REST API** when:
+				- You need mature, stable, well-documented interfaces
+				- Your use case requires specialized operations (e.g., direct page copying)
+				- You prioritize maximum feature coverage and tooling support
+				- You have existing REST integrations or team familiarity with REST
+			- **Consider GraphQL API** when:
+				- You need efficient data retrieval with related entities in single queries
+				- You want to minimize over-fetching and reduce request count
+				- You can work with evolving APIs (GraphQL was in beta as of March 2022)
+				- Your use case benefits from schema introspection and strongly-typed queries
+			- **Performance Note**: Community testing has shown REST v1 may outperform GraphQL and REST v2 in some scenarios, suggesting performance evaluation is use-case specific
+		- **Beta Status**: GraphQL APIs were released in beta as of March 2022, emphasizing that they are still evolving and subject to change based on user feedback
+		- **Deprecation Concerns**: Developer community discussions have raised concerns about REST v1 deprecation and the readiness of newer APIs to fully replace older versions
+		- See also: [Confluence GraphQL API Documentation](https://developer.atlassian.com/cloud/confluence/graphql/), [Community Performance Discussion](https://community.developer.atlassian.com/t/performance-rest-vs-graphql/69254)
 	- ## Misconceptions
 		- GraphQL is always faster than REST → **False**. Performance depends on query complexity and server implementation. Some GraphQL queries may be slower than equivalent REST calls
+		- GraphQL cannot create or modify content → **False**. GraphQL provides mutations like `createPage`, `updatePage`, and `deletePage` for content management operations. Both APIs support write operations, though REST may offer more specialized endpoints (like direct page copying)
+		- GraphQL can do everything REST can do → **Partially false**. While GraphQL has mutations for CRUD operations, REST may have specialized endpoints that don't have direct GraphQL equivalents (e.g., dedicated copy endpoints). For duplicating pages, REST's copy endpoint is more straightforward than GraphQL's query-then-create approach
 		- REST v2 is just an updated version of v1 → **False**. REST v2 was redesigned for performance and removed expansions, requiring a different approach to data retrieval
-		- GraphQL eliminates the need for REST → **False**. Both APIs serve different purposes. REST may be simpler for straightforward CRUD operations, while GraphQL excels at complex nested data retrieval
+		- GraphQL eliminates the need for REST → **False**. Both APIs serve different purposes. REST may have specialized operations and better tooling for certain workflows, while GraphQL excels at complex nested data retrieval and provides a unified interface for queries and mutations
 		- GraphQL beta fields are unstable and shouldn't be used → **Partially true**. Beta fields can change without notice and are intended for experimentation, but they provide access to newer features
 	- ## Related
 		- [[Atlassian/Confluence/API/GraphQL]]