From c4f8ba0561c5e40797ed1a40d4a519234dcdcb61 Mon Sep 17 00:00:00 2001 From: Matthew Ratzke Date: Wed, 7 Feb 2024 19:40:29 -0700 Subject: [PATCH 1/9] Create TN0047-error-status-code-200.mdx --- .../TN0047-error-status-code-200.mdx | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 src/content/technotes/TN0047-error-status-code-200.mdx diff --git a/src/content/technotes/TN0047-error-status-code-200.mdx b/src/content/technotes/TN0047-error-status-code-200.mdx new file mode 100644 index 000000000..92a65db0c --- /dev/null +++ b/src/content/technotes/TN0047-error-status-code-200.mdx @@ -0,0 +1,48 @@ +--- +title: Error! Status Code 200? +subtitle: Granular error handling in your API +description: Learn how to frame status codes within graphql errors +published: 2024-02-09 +id: TN0047 +tags: [best-practices, error-handling] +--- + +In the realm of API development, HTTP status codes serve as crucial indicators of request success or failure. +However, when it comes to GraphQL, the traditional approach of using REST/HTTP error codes becomes inadequate. +GraphQL introduces a paradigm shift in how APIs are designed and operated, rendering conventional status codes insufficient for capturing the nuances of GraphQL operations, especially in the context of parallel operations. +Let's delve into why GraphQL 200 status codes are the new norm and why using REST/HTTP error codes doesn't make sense in the GraphQL ecosystem. + +## The Nature of GraphQL Operations + +In a typical REST API, each endpoint corresponds to a specific resource or action, making it straightforward to map HTTP status codes to the outcome of each request. +However, GraphQL operates differently. Instead of multiple endpoints, GraphQL has a single endpoint that serves as an entry point for executing queries, mutations, and subscriptions. +This unified approach allows clients to request precisely the data they need in a single round trip to the server. + +## Granular Error Handling + +GraphQL offers granular error handling through its response structure. +In a GraphQL response, along with the data requested by the client, the server can include an array of errors, each containing detailed information about what went wrong. +This level of granularity enables clients to understand and react to errors more effectively than traditional HTTP status codes would allow. + +## Parallel Execution and Partial Results + +One of the most powerful features of GraphQL is its ability to execute multiple operations in parallel. +This means that even if one part of a GraphQL operation fails, other parts may still succeed. +In contrast, REST APIs typically follow a serial execution model, where one failed request can halt the entire process. +Therefore, using HTTP status codes to convey the outcome of parallel GraphQL operations would be impractical and misleading. + +## The Significance of GraphQL 200 Status Codes + +In GraphQL, the presence of a 200 status code indicates that the request was successful from the router's perspective. +This does not necessarily mean that the client received all the data it requested without any errors. +Instead, it signifies that the GraphQL operation as a whole was processed without encountering any issues, regardless of the outcome of individual fields. + +## Conclusion + +The GraphQL 200 status codes signify the successful processing of a request at the router level, but they do not encapsulate the outcome of individual operations or the presence of errors within a GraphQL response. +Attempting to shoehorn HTTP error codes into the GraphQL paradigm overlooks the unique characteristics and capabilities of GraphQL, such as granular error handling, parallel execution, and asynchronous patterns. +As GraphQL continues to gain traction in the API landscape, embracing GraphQL-specific conventions, including 200 status codes, is essential for building robust and efficient GraphQL APIs. + +## Additional Resources + +- [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/) \ No newline at end of file From 6980486b95f6eadc17d9809af883dc0cdba5ab2d Mon Sep 17 00:00:00 2001 From: Matthew Ratzke Date: Wed, 7 Feb 2024 19:41:56 -0700 Subject: [PATCH 2/9] Update _redirects --- src/content/technotes/_redirects | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/technotes/_redirects b/src/content/technotes/_redirects index 82656a834..af44da142 100644 --- a/src/content/technotes/_redirects +++ b/src/content/technotes/_redirects @@ -47,4 +47,5 @@ /TN0043 /docs/technotes/TN0043-using-graphql-for-abstraction /TN0044 /docs/technotes/TN0044-graphql-and-rest-together /TN0045 /docs/technotes/TN0045-router_resource_estimator -/TN0046 /docs/technotes/TN0046-managing-graph-environments-using-variants \ No newline at end of file +/TN0046 /docs/technotes/TN0046-managing-graph-environments-using-variants +/TN0047 /docs/technotes/TN0047-error-status-code-200 \ No newline at end of file From cc4b5709e4a3639be032a89ebc51da14c62c4fc7 Mon Sep 17 00:00:00 2001 From: Matthew Ratzke Date: Wed, 7 Feb 2024 23:02:15 -0700 Subject: [PATCH 3/9] wip --- .../TN0047-error-status-code-200.mdx | 27 +++++++++---------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/src/content/technotes/TN0047-error-status-code-200.mdx b/src/content/technotes/TN0047-error-status-code-200.mdx index 92a65db0c..6ddb4cfea 100644 --- a/src/content/technotes/TN0047-error-status-code-200.mdx +++ b/src/content/technotes/TN0047-error-status-code-200.mdx @@ -10,9 +10,15 @@ tags: [best-practices, error-handling] In the realm of API development, HTTP status codes serve as crucial indicators of request success or failure. However, when it comes to GraphQL, the traditional approach of using REST/HTTP error codes becomes inadequate. GraphQL introduces a paradigm shift in how APIs are designed and operated, rendering conventional status codes insufficient for capturing the nuances of GraphQL operations, especially in the context of parallel operations. -Let's delve into why GraphQL 200 status codes are the new norm and why using REST/HTTP error codes doesn't make sense in the GraphQL ecosystem. -## The Nature of GraphQL Operations +> +> TLDR; The GraphQL 200 status codes signify the successful processing of a request at the Apollo Router level, but they do not encapsulate the outcome of individual operations or the presence of errors within a GraphQL response. +> Attempting to shoehorn HTTP error codes into the GraphQL paradigm overlooks the unique characteristics and capabilities of GraphQL, such as granular error handling, parallel execution, and asynchronous patterns. +> +> You can learn more about status codes in GraphQL by reading the [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/) specification. +> + +## Nature of GraphQL Operations In a typical REST API, each endpoint corresponds to a specific resource or action, making it straightforward to map HTTP status codes to the outcome of each request. However, GraphQL operates differently. Instead of multiple endpoints, GraphQL has a single endpoint that serves as an entry point for executing queries, mutations, and subscriptions. @@ -29,20 +35,11 @@ This level of granularity enables clients to understand and react to errors more One of the most powerful features of GraphQL is its ability to execute multiple operations in parallel. This means that even if one part of a GraphQL operation fails, other parts may still succeed. In contrast, REST APIs typically follow a serial execution model, where one failed request can halt the entire process. + Therefore, using HTTP status codes to convey the outcome of parallel GraphQL operations would be impractical and misleading. -## The Significance of GraphQL 200 Status Codes +## Significance of 200 Status Codes -In GraphQL, the presence of a 200 status code indicates that the request was successful from the router's perspective. +In GraphQL, the presence of a 200 status code indicates that the request was successful from the Apollo Router's perspective. This does not necessarily mean that the client received all the data it requested without any errors. -Instead, it signifies that the GraphQL operation as a whole was processed without encountering any issues, regardless of the outcome of individual fields. - -## Conclusion - -The GraphQL 200 status codes signify the successful processing of a request at the router level, but they do not encapsulate the outcome of individual operations or the presence of errors within a GraphQL response. -Attempting to shoehorn HTTP error codes into the GraphQL paradigm overlooks the unique characteristics and capabilities of GraphQL, such as granular error handling, parallel execution, and asynchronous patterns. -As GraphQL continues to gain traction in the API landscape, embracing GraphQL-specific conventions, including 200 status codes, is essential for building robust and efficient GraphQL APIs. - -## Additional Resources - -- [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/) \ No newline at end of file +Instead, it signifies that the GraphQL operation as a whole was processed without encountering any issues, regardless of the outcome of individual field resolvers. From 347ab0192ff8b7764609626d75225f5eaf3c7c21 Mon Sep 17 00:00:00 2001 From: Matthew Ratzke Date: Wed, 7 Feb 2024 23:14:41 -0700 Subject: [PATCH 4/9] Update TN0047-error-status-code-200.mdx --- src/content/technotes/TN0047-error-status-code-200.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/technotes/TN0047-error-status-code-200.mdx b/src/content/technotes/TN0047-error-status-code-200.mdx index 6ddb4cfea..10c22cb48 100644 --- a/src/content/technotes/TN0047-error-status-code-200.mdx +++ b/src/content/technotes/TN0047-error-status-code-200.mdx @@ -1,7 +1,7 @@ --- title: Error! Status Code 200? subtitle: Granular error handling in your API -description: Learn how to frame status codes within graphql errors +description: Learn GraphQL uniquly handles errors and how that compares to traditional REST APIs. published: 2024-02-09 id: TN0047 tags: [best-practices, error-handling] From 66d6440b7bc3a6166067b4ab62b58425e61a7d51 Mon Sep 17 00:00:00 2001 From: Matt Ratzke Date: Thu, 8 Feb 2024 10:57:40 -0700 Subject: [PATCH 5/9] Update src/content/technotes/TN0047-error-status-code-200.mdx Co-authored-by: Shane Myrick --- src/content/technotes/TN0047-error-status-code-200.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/technotes/TN0047-error-status-code-200.mdx b/src/content/technotes/TN0047-error-status-code-200.mdx index 10c22cb48..429e52606 100644 --- a/src/content/technotes/TN0047-error-status-code-200.mdx +++ b/src/content/technotes/TN0047-error-status-code-200.mdx @@ -12,7 +12,8 @@ However, when it comes to GraphQL, the traditional approach of using REST/HTTP e GraphQL introduces a paradigm shift in how APIs are designed and operated, rendering conventional status codes insufficient for capturing the nuances of GraphQL operations, especially in the context of parallel operations. > -> TLDR; The GraphQL 200 status codes signify the successful processing of a request at the Apollo Router level, but they do not encapsulate the outcome of individual operations or the presence of errors within a GraphQL response. +> **TLDR;** The GraphQL 200 status codes signify the client has sent a request, the operation is valid GraphQL against the schema, and the GraphQL server was able to return a spec-compliant GraphQL response, but they do not encapsulate the outcome of individual fields or the presence of errors within the GraphQL response. +> > Attempting to shoehorn HTTP error codes into the GraphQL paradigm overlooks the unique characteristics and capabilities of GraphQL, such as granular error handling, parallel execution, and asynchronous patterns. > > You can learn more about status codes in GraphQL by reading the [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/) specification. From fa733e6dd14fca0c25941e7e0e60bf05cf81faec Mon Sep 17 00:00:00 2001 From: Matt Ratzke Date: Thu, 8 Feb 2024 10:58:01 -0700 Subject: [PATCH 6/9] Update src/content/technotes/TN0047-error-status-code-200.mdx Co-authored-by: Shane Myrick --- src/content/technotes/TN0047-error-status-code-200.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/technotes/TN0047-error-status-code-200.mdx b/src/content/technotes/TN0047-error-status-code-200.mdx index 429e52606..58e12c604 100644 --- a/src/content/technotes/TN0047-error-status-code-200.mdx +++ b/src/content/technotes/TN0047-error-status-code-200.mdx @@ -22,7 +22,7 @@ GraphQL introduces a paradigm shift in how APIs are designed and operated, rende ## Nature of GraphQL Operations In a typical REST API, each endpoint corresponds to a specific resource or action, making it straightforward to map HTTP status codes to the outcome of each request. -However, GraphQL operates differently. Instead of multiple endpoints, GraphQL has a single endpoint that serves as an entry point for executing queries, mutations, and subscriptions. +However, GraphQL operates differently. Instead of multiple endpoints, GraphQL has a single endpoint that serves as an entry point for executing many different queries, mutations, and subscriptions. You can even execute more then one query in a single request. This unified approach allows clients to request precisely the data they need in a single round trip to the server. ## Granular Error Handling From eb99022bcb1e014a7a1de794cafd527b79d4c485 Mon Sep 17 00:00:00 2001 From: Matt Ratzke Date: Thu, 8 Feb 2024 10:58:58 -0700 Subject: [PATCH 7/9] Update src/content/technotes/TN0047-error-status-code-200.mdx Co-authored-by: Shane Myrick --- src/content/technotes/TN0047-error-status-code-200.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/technotes/TN0047-error-status-code-200.mdx b/src/content/technotes/TN0047-error-status-code-200.mdx index 58e12c604..a5dc514c2 100644 --- a/src/content/technotes/TN0047-error-status-code-200.mdx +++ b/src/content/technotes/TN0047-error-status-code-200.mdx @@ -28,7 +28,7 @@ This unified approach allows clients to request precisely the data they need in ## Granular Error Handling GraphQL offers granular error handling through its response structure. -In a GraphQL response, along with the data requested by the client, the server can include an array of errors, each containing detailed information about what went wrong. +In a GraphQL response, you have two key fields: the `data` field represents all the information the server could respond with that matches the clients request, and `errors` field is an array containing detailed information about what may have gone wrong when making the request. If the server is able to return a response in this shape, it is matching that GraphQL spec, even if it only contains the `errors` field. This level of granularity enables clients to understand and react to errors more effectively than traditional HTTP status codes would allow. ## Parallel Execution and Partial Results From e1a43090210c4440b3d09906e892980ed7de4d5c Mon Sep 17 00:00:00 2001 From: Matt Ratzke Date: Thu, 8 Feb 2024 10:59:46 -0700 Subject: [PATCH 8/9] Update TN0047-error-status-code-200.mdx --- src/content/technotes/TN0047-error-status-code-200.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/technotes/TN0047-error-status-code-200.mdx b/src/content/technotes/TN0047-error-status-code-200.mdx index a5dc514c2..39352c235 100644 --- a/src/content/technotes/TN0047-error-status-code-200.mdx +++ b/src/content/technotes/TN0047-error-status-code-200.mdx @@ -39,7 +39,7 @@ In contrast, REST APIs typically follow a serial execution model, where one fail Therefore, using HTTP status codes to convey the outcome of parallel GraphQL operations would be impractical and misleading. -## Significance of 200 Status Codes +## Summary In GraphQL, the presence of a 200 status code indicates that the request was successful from the Apollo Router's perspective. This does not necessarily mean that the client received all the data it requested without any errors. From 153ee1f06ed5e5754a2156f4caad01a2b58f20ae Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Mon, 18 Mar 2024 10:18:47 -0700 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Edward Huang --- .../TN0047-error-status-code-200.mdx | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/src/content/technotes/TN0047-error-status-code-200.mdx b/src/content/technotes/TN0047-error-status-code-200.mdx index 39352c235..e8792b6e3 100644 --- a/src/content/technotes/TN0047-error-status-code-200.mdx +++ b/src/content/technotes/TN0047-error-status-code-200.mdx @@ -1,7 +1,7 @@ --- title: Error! Status Code 200? subtitle: Granular error handling in your API -description: Learn GraphQL uniquly handles errors and how that compares to traditional REST APIs. +description: Learn how GraphQL uniquely handles errors and how that compares to traditional REST APIs. published: 2024-02-09 id: TN0047 tags: [best-practices, error-handling] @@ -12,14 +12,16 @@ However, when it comes to GraphQL, the traditional approach of using REST/HTTP e GraphQL introduces a paradigm shift in how APIs are designed and operated, rendering conventional status codes insufficient for capturing the nuances of GraphQL operations, especially in the context of parallel operations. > -> **TLDR;** The GraphQL 200 status codes signify the client has sent a request, the operation is valid GraphQL against the schema, and the GraphQL server was able to return a spec-compliant GraphQL response, but they do not encapsulate the outcome of individual fields or the presence of errors within the GraphQL response. +> **TLDR;** In GraphQL, the presence of a 200 status code indicates that the request was successful from the Apollo Router's perspective, but it doesn't necessarily mean that the client received all the data it requested without any errors. + +The GraphQL 200 status codes don't encapsulate the outcome of individual fields or the presence of errors within the GraphQL response. Rather, they signify that the client has sent a request, the operation is valid GraphQL against the schema, and the GraphQL server was able to return a spec-compliant GraphQL response. > -> Attempting to shoehorn HTTP error codes into the GraphQL paradigm overlooks the unique characteristics and capabilities of GraphQL, such as granular error handling, parallel execution, and asynchronous patterns. +> Shoehorning HTTP error codes into the GraphQL paradigm overlooks the unique characteristics and capabilities of GraphQL, such as granular error handling, parallel execution, and asynchronous patterns. > -> You can learn more about status codes in GraphQL by reading the [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/) specification. +> To learn more about GraphQL status codes, see the [GraphQL-over-HTTP](https://graphql.github.io/graphql-over-http/draft/) specification. > -## Nature of GraphQL Operations +## Nature of GraphQL operations In a typical REST API, each endpoint corresponds to a specific resource or action, making it straightforward to map HTTP status codes to the outcome of each request. However, GraphQL operates differently. Instead of multiple endpoints, GraphQL has a single endpoint that serves as an entry point for executing many different queries, mutations, and subscriptions. You can even execute more then one query in a single request. @@ -28,13 +30,16 @@ This unified approach allows clients to request precisely the data they need in ## Granular Error Handling GraphQL offers granular error handling through its response structure. -In a GraphQL response, you have two key fields: the `data` field represents all the information the server could respond with that matches the clients request, and `errors` field is an array containing detailed information about what may have gone wrong when making the request. If the server is able to return a response in this shape, it is matching that GraphQL spec, even if it only contains the `errors` field. +A GraphQL response contains two key fields: +- The `data` field represents all the information the server could respond with that matches the clients request. +- The `errors` field is an array containing detailed information about what may have gone wrong when making the request. + +A server returns a response in this shape, even if it only contains the `errors` field. This level of granularity enables clients to understand and react to errors more effectively than traditional HTTP status codes would allow. -## Parallel Execution and Partial Results +## Parallel execution and partial results -One of the most powerful features of GraphQL is its ability to execute multiple operations in parallel. -This means that even if one part of a GraphQL operation fails, other parts may still succeed. +One of the most powerful features of GraphQL is its ability to execute multiple operations in parallel: if one part of a GraphQL operation fails, other parts may still succeed. In contrast, REST APIs typically follow a serial execution model, where one failed request can halt the entire process. Therefore, using HTTP status codes to convey the outcome of parallel GraphQL operations would be impractical and misleading. @@ -42,5 +47,5 @@ Therefore, using HTTP status codes to convey the outcome of parallel GraphQL ope ## Summary In GraphQL, the presence of a 200 status code indicates that the request was successful from the Apollo Router's perspective. -This does not necessarily mean that the client received all the data it requested without any errors. +This doesn't necessarily mean that the client received all the data it requested without any errors. Instead, it signifies that the GraphQL operation as a whole was processed without encountering any issues, regardless of the outcome of individual field resolvers.