|
| 1 | +tags:: [[Diataxis/Explanation]] |
| 2 | +- # GraphQL vs REST APIs Conceptual Overview |
| 3 | + - ## Overview |
| 4 | + - GraphQL and REST are two distinct API paradigms available in Atlassian Confluence Cloud, each offering different approaches to data retrieval and integration |
| 5 | + - GraphQL allows clients to request precisely the data they need in a single query, while REST uses traditional endpoint-based architecture with multiple resources |
| 6 | + - Understanding the differences helps developers choose the right API approach for their specific integration needs |
| 7 | + - ## Context |
| 8 | + - Confluence Cloud historically provided REST APIs (v1 and v2) for integration needs |
| 9 | + - GraphQL was introduced later as a modern alternative addressing limitations of REST in complex data retrieval scenarios |
| 10 | + - REST v2 was optimized for performance but removed expansions, creating a need for multiple requests to gather related data |
| 11 | + - GraphQL addresses the over-fetching and under-fetching problems common with REST by allowing clients to specify exact data requirements |
| 12 | + - Both APIs coexist to serve different use cases and developer preferences |
| 13 | + - ## Key Principles |
| 14 | + - **Query Efficiency**: GraphQL enables fetching multiple related resources in a single request, while REST typically requires multiple endpoint calls |
| 15 | + - **Data Control**: GraphQL clients specify exactly what fields they need, reducing over-fetching of unnecessary data |
| 16 | + - **Schema Evolution**: GraphQL uses continuous schema evolution with beta fields and deprecation periods, while REST relies on explicit versioning (v1, v2) |
| 17 | + - **Flexibility vs Stability**: REST provides stable, versioned endpoints with predictable behavior, while GraphQL offers flexibility but may change more frequently |
| 18 | + - **Tooling Maturity**: REST benefits from extensive tooling and community support, while GraphQL provides newer tools like GraphQL Explorer for query discovery |
| 19 | + - ## Mechanism |
| 20 | + - **REST API Approach**: |
| 21 | + - Uses HTTP methods (GET, POST, PUT, DELETE) on resource-based endpoints |
| 22 | + - Endpoints are organized by resource type (e.g., `/wiki/rest/api/content`, `/wiki/rest/api/space`) |
| 23 | + - Returns complete resource representations unless filtered server-side |
| 24 | + - Versioning handled through URL paths (`/api/v1/`, `/api/v2/`) |
| 25 | + - Authentication via OAuth 2.0 or Basic auth |
| 26 | + - **GraphQL API Approach**: |
| 27 | + - Single endpoint for all queries (typically `/graphql`) |
| 28 | + - Clients send queries specifying exact fields and relationships needed |
| 29 | + - Query language allows nested data fetching in one request |
| 30 | + - Schema introspection enables self-documenting APIs |
| 31 | + - Authentication via OAuth 2.0 or JWT for cloud apps |
| 32 | + - Beta fields marked for experimental features that may change |
| 33 | + - ## Examples |
| 34 | + - **REST API Example**: Fetching a page and its space requires multiple requests: |
| 35 | + - Request 1: `GET /wiki/rest/api/content/{id}` to get page details |
| 36 | + - Request 2: `GET /wiki/rest/api/space/{spaceKey}` to get space information |
| 37 | + - Result: Two separate HTTP requests with potential over-fetching |
| 38 | + - **GraphQL API Example**: Fetching the same data in a single query: |
| 39 | + ~~~ |
| 40 | + query { |
| 41 | + content(id: "123") { |
| 42 | + title |
| 43 | + space { |
| 44 | + key |
| 45 | + name |
| 46 | + } |
| 47 | + } |
| 48 | + } |
| 49 | + ~~~ |
| 50 | + - Result: One request fetching only the specified fields |
| 51 | + - **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 |
| 52 | + - ## Misconceptions |
| 53 | + - 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 |
| 54 | + - 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 |
| 55 | + - 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 |
| 56 | + - 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 |
| 57 | + - ## Related |
| 58 | + - [[Atlassian/Confluence/API/GraphQL]] |
| 59 | + - [[Atlassian/Confluence/API/REST/v2]] |
| 60 | + - [[Atlassian/Confluence/API/REST/v1]] |
| 61 | + - [[Atlassian/Confluence/API]] |
| 62 | + |
0 commit comments