From 1125955322b3e307de6b3b9ce21d210183d76b11 Mon Sep 17 00:00:00 2001 From: Theo <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 11:07:51 +0000 Subject: [PATCH 01/10] Explanation document: which queries to use --- docs/explanation/which-queries-to-use.md | 45 ++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/explanation/which-queries-to-use.md diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md new file mode 100644 index 00000000..e63247f3 --- /dev/null +++ b/docs/explanation/which-queries-to-use.md @@ -0,0 +1,45 @@ +# GET vs POST Requests in WPGraphQL: Choosing the right method + +This guide explains the differences between using a GET request with a query parameter versus a POST request to the `/graphql` endpoint. + +WPGraphQL exposes a GraphQL endpoint that developers can use to interact with the WordPress backend and retrieve data. + +The plugin provides two primary ways to interact with this API: + +1. The pretty URL endpoint `/graphql` +2. The query-string-based endpoint `/index.php?graphql` + +Both serve the same purpose of providing access to the GraphQL API, but they function slightly differently. + +## The default `/graphql` endpoint + +The `/graphql` default endpoint is the preferred choice for most users because it is easy to read, share, and remember. + +WPGraphQL allows you to customize the `/graphql` endpoint using a filter. If you'd like to change the endpoint to something more specific to your site, you can do so with a simple code snippet. + +```php +function my_new_graphql_endpoint() { + return 'my_endpoint'; +}; + +add_filter( 'graphql_endpoint', 'my_new_graphql_endpoint' ); +``` +This code would change the default `/graphql` endpoint to `/my_endpoint`. + +## The query string endpoint: `/index.php?graphql` + +WPGraphQL also provides an alternative endpoint that works even if pretty permalinks are not enabled. This endpoint is based on the standard WordPress `index.php` file, with a query string parameter: + +```php +/index.php?graphql +``` + +This query-string endpoint serves as a fallback for WordPress sites that do not have pretty permalinks enabled. If a site is running with the default URL structure (e.g., `example.com/?p=123`), the `/graphql` pretty URL might not work. In this case, `/index.php?graphql` can be used to access the GraphQL API. + +## Which one should you use and why? + +If you have pretty permalinks enabled, it’s best to use the clean `/graphql` endpoint. + +WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `index.php?graphql` is still valid. In this case, WordPress will handle the request through `index.php`, with the graphql query parameter routing it to WPGraphQL. + +If there is any issue with the `/graphql` endpoint (perhaps due to rewrite rules, .htaccess configurations, or plugin conflicts), the `/index.php?graphql` endpoint can be a quick alternative to ensure your requests are still processed correctly. \ No newline at end of file From f18b729b7275898e9880d5d767fe9846e1692a81 Mon Sep 17 00:00:00 2001 From: Theo <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 11:13:00 +0000 Subject: [PATCH 02/10] chore: update document title --- docs/explanation/which-queries-to-use.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md index e63247f3..8d43439d 100644 --- a/docs/explanation/which-queries-to-use.md +++ b/docs/explanation/which-queries-to-use.md @@ -1,6 +1,4 @@ -# GET vs POST Requests in WPGraphQL: Choosing the right method - -This guide explains the differences between using a GET request with a query parameter versus a POST request to the `/graphql` endpoint. +# Which WPGraphQL endpoints to use: /graphql vs ?graphql WPGraphQL exposes a GraphQL endpoint that developers can use to interact with the WordPress backend and retrieve data. From 7aea0624738e9dfd9350a650f784666ad8cf79e1 Mon Sep 17 00:00:00 2001 From: Theofanis Despoudis <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 17:52:05 +0000 Subject: [PATCH 03/10] Update docs/explanation/which-queries-to-use.md Co-authored-by: Alex Moon --- docs/explanation/which-queries-to-use.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md index 8d43439d..46f3dfa1 100644 --- a/docs/explanation/which-queries-to-use.md +++ b/docs/explanation/which-queries-to-use.md @@ -26,7 +26,7 @@ This code would change the default `/graphql` endpoint to `/my_endpoint`. ## The query string endpoint: `/index.php?graphql` -WPGraphQL also provides an alternative endpoint that works even if pretty permalinks are not enabled. This endpoint is based on the standard WordPress `index.php` file, with a query string parameter: +The `/index.php?graphql` endpoint is the preferred choice for those looking for stability and compatibility. ```php /index.php?graphql From 69b1def9b080dc2d86b1078b673514cafb6f30c9 Mon Sep 17 00:00:00 2001 From: Theofanis Despoudis <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 17:52:16 +0000 Subject: [PATCH 04/10] Update docs/explanation/which-queries-to-use.md Co-authored-by: Alex Moon --- docs/explanation/which-queries-to-use.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md index 46f3dfa1..daa50b51 100644 --- a/docs/explanation/which-queries-to-use.md +++ b/docs/explanation/which-queries-to-use.md @@ -28,10 +28,6 @@ This code would change the default `/graphql` endpoint to `/my_endpoint`. The `/index.php?graphql` endpoint is the preferred choice for those looking for stability and compatibility. -```php -/index.php?graphql -``` - This query-string endpoint serves as a fallback for WordPress sites that do not have pretty permalinks enabled. If a site is running with the default URL structure (e.g., `example.com/?p=123`), the `/graphql` pretty URL might not work. In this case, `/index.php?graphql` can be used to access the GraphQL API. ## Which one should you use and why? From 1e45820dbba2e24b3520698dd170b1b0c21bf663 Mon Sep 17 00:00:00 2001 From: Theofanis Despoudis <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 17:52:41 +0000 Subject: [PATCH 05/10] Update docs/explanation/which-queries-to-use.md Co-authored-by: Alex Moon --- docs/explanation/which-queries-to-use.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md index daa50b51..103f0b52 100644 --- a/docs/explanation/which-queries-to-use.md +++ b/docs/explanation/which-queries-to-use.md @@ -32,7 +32,7 @@ This query-string endpoint serves as a fallback for WordPress sites that do not ## Which one should you use and why? -If you have pretty permalinks enabled, it’s best to use the clean `/graphql` endpoint. +If your application only talks to a WP instance(s) with pretty permalinks enabled and you trust that will not change, it’s safe to use the clean `/graphql` endpoint. WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `index.php?graphql` is still valid. In this case, WordPress will handle the request through `index.php`, with the graphql query parameter routing it to WPGraphQL. From fd02ababd7daef5e9bf9d6e2e78a9022a62aedc2 Mon Sep 17 00:00:00 2001 From: Theofanis Despoudis <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 17:53:08 +0000 Subject: [PATCH 06/10] Update docs/explanation/which-queries-to-use.md Co-authored-by: Alex Moon --- docs/explanation/which-queries-to-use.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md index 103f0b52..d286840c 100644 --- a/docs/explanation/which-queries-to-use.md +++ b/docs/explanation/which-queries-to-use.md @@ -34,6 +34,6 @@ This query-string endpoint serves as a fallback for WordPress sites that do not If your application only talks to a WP instance(s) with pretty permalinks enabled and you trust that will not change, it’s safe to use the clean `/graphql` endpoint. -WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `index.php?graphql` is still valid. In this case, WordPress will handle the request through `index.php`, with the graphql query parameter routing it to WPGraphQL. +If you don't know or don't trust the config to change, `/index.php?graphql` is recommended. WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `/index.php?graphql` is still valid. If there is any issue with the `/graphql` endpoint (perhaps due to rewrite rules, .htaccess configurations, or plugin conflicts), the `/index.php?graphql` endpoint can be a quick alternative to ensure your requests are still processed correctly. \ No newline at end of file From 238176f196aea4fc036fbf766708d9229b9b442c Mon Sep 17 00:00:00 2001 From: Theofanis Despoudis <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 17:53:25 +0000 Subject: [PATCH 07/10] Update docs/explanation/which-queries-to-use.md Co-authored-by: Alex Moon --- docs/explanation/which-queries-to-use.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md index d286840c..b2e260b8 100644 --- a/docs/explanation/which-queries-to-use.md +++ b/docs/explanation/which-queries-to-use.md @@ -34,6 +34,4 @@ This query-string endpoint serves as a fallback for WordPress sites that do not If your application only talks to a WP instance(s) with pretty permalinks enabled and you trust that will not change, it’s safe to use the clean `/graphql` endpoint. -If you don't know or don't trust the config to change, `/index.php?graphql` is recommended. WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `/index.php?graphql` is still valid. - -If there is any issue with the `/graphql` endpoint (perhaps due to rewrite rules, .htaccess configurations, or plugin conflicts), the `/index.php?graphql` endpoint can be a quick alternative to ensure your requests are still processed correctly. \ No newline at end of file +If you don't know or don't trust the config to change, `/index.php?graphql` is recommended. WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `/index.php?graphql` is still valid. \ No newline at end of file From 7816600d79b19b9ee38650a0e5d7a81db5d6a84c Mon Sep 17 00:00:00 2001 From: Theofanis Despoudis <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 17:56:51 +0000 Subject: [PATCH 08/10] Update docs/explanation/which-queries-to-use.md Co-authored-by: Alex Moon --- docs/explanation/which-queries-to-use.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md index b2e260b8..df9483d0 100644 --- a/docs/explanation/which-queries-to-use.md +++ b/docs/explanation/which-queries-to-use.md @@ -32,6 +32,7 @@ This query-string endpoint serves as a fallback for WordPress sites that do not ## Which one should you use and why? +While the `/graphql` endpoint is easy and clean; rewrite rules, .htaccess configurations, or plugin conflicts can all break this endpoint. The `/index.php?graphql` endpoint can be a more resilient alternative to ensure your requests are still processed correctly. If your application only talks to a WP instance(s) with pretty permalinks enabled and you trust that will not change, it’s safe to use the clean `/graphql` endpoint. If you don't know or don't trust the config to change, `/index.php?graphql` is recommended. WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `/index.php?graphql` is still valid. \ No newline at end of file From 643023d3ff96e5d1fe2f3aa38a78539d7195e4b9 Mon Sep 17 00:00:00 2001 From: Theo <328805+theodesp@users.noreply.github.com> Date: Tue, 18 Mar 2025 17:58:43 +0000 Subject: [PATCH 09/10] chore: review feedback --- docs/explanation/graphql-endpoints.md | 40 +++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/explanation/graphql-endpoints.md diff --git a/docs/explanation/graphql-endpoints.md b/docs/explanation/graphql-endpoints.md new file mode 100644 index 00000000..de92b6fe --- /dev/null +++ b/docs/explanation/graphql-endpoints.md @@ -0,0 +1,40 @@ +# Which WPGraphQL endpoints to use: /graphql vs ?graphql + +WPGraphQL exposes a GraphQL endpoint that developers can use to interact with the WordPress backend and retrieve data. + +The plugin provides two primary ways to interact with this API: + +1. The pretty URL endpoint `/graphql` +2. The query-string-based endpoint `/index.php?graphql` + +Both serve the same purpose of providing access to the GraphQL API, but they function slightly differently. + +## The default `/graphql` endpoint + +The `/graphql` default endpoint is the preferred choice for most users because it is easy to read, share, and remember. + +## The query string endpoint: `/index.php?graphql` + +The `/index.php?graphql` endpoint is the preferred choice for those looking for stability and compatibility. + +This query-string endpoint serves as a fallback for WordPress sites that do not have pretty permalinks enabled. If a site is running with the default URL structure (e.g., `example.com/?p=123`), the `/graphql` pretty URL might not work. In this case, `/index.php?graphql` can be used to access the GraphQL API. + +## Which one should you use and why? + +If your application only talks to a WP instance(s) with pretty permalinks enabled and you trust that will not change, it’s safe to use the clean `/graphql` endpoint. + +If you don't know or don't trust the config to change, `/index.php?graphql` is recommended. WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `/index.php?graphql` is still valid. + +## Customizing the GraphQL Endpoint +WPGraphQL allows you to customize the `/graphql` endpoint using a filter. If you'd like to change the endpoint to something more specific to your site, you can do so with a simple code snippet. + +```php +function my_new_graphql_endpoint() { + return 'my_endpoint'; +}; + +add_filter( 'graphql_endpoint', 'my_new_graphql_endpoint' ); +``` +This code would change the default `/graphql` endpoint to `/my_endpoint`. + +Alternatively, you can configure the endpoint directly in the **WPGraphQL Settings** under **GraphQL Endpoint**, without needing to modify your code. \ No newline at end of file From d61b649099700ecb322d2e038b321f16bca5e15b Mon Sep 17 00:00:00 2001 From: Alex Moon Date: Tue, 18 Mar 2025 12:33:13 -0700 Subject: [PATCH 10/10] Delete docs/explanation/which-queries-to-use.md --- docs/explanation/which-queries-to-use.md | 38 ------------------------ 1 file changed, 38 deletions(-) delete mode 100644 docs/explanation/which-queries-to-use.md diff --git a/docs/explanation/which-queries-to-use.md b/docs/explanation/which-queries-to-use.md deleted file mode 100644 index df9483d0..00000000 --- a/docs/explanation/which-queries-to-use.md +++ /dev/null @@ -1,38 +0,0 @@ -# Which WPGraphQL endpoints to use: /graphql vs ?graphql - -WPGraphQL exposes a GraphQL endpoint that developers can use to interact with the WordPress backend and retrieve data. - -The plugin provides two primary ways to interact with this API: - -1. The pretty URL endpoint `/graphql` -2. The query-string-based endpoint `/index.php?graphql` - -Both serve the same purpose of providing access to the GraphQL API, but they function slightly differently. - -## The default `/graphql` endpoint - -The `/graphql` default endpoint is the preferred choice for most users because it is easy to read, share, and remember. - -WPGraphQL allows you to customize the `/graphql` endpoint using a filter. If you'd like to change the endpoint to something more specific to your site, you can do so with a simple code snippet. - -```php -function my_new_graphql_endpoint() { - return 'my_endpoint'; -}; - -add_filter( 'graphql_endpoint', 'my_new_graphql_endpoint' ); -``` -This code would change the default `/graphql` endpoint to `/my_endpoint`. - -## The query string endpoint: `/index.php?graphql` - -The `/index.php?graphql` endpoint is the preferred choice for those looking for stability and compatibility. - -This query-string endpoint serves as a fallback for WordPress sites that do not have pretty permalinks enabled. If a site is running with the default URL structure (e.g., `example.com/?p=123`), the `/graphql` pretty URL might not work. In this case, `/index.php?graphql` can be used to access the GraphQL API. - -## Which one should you use and why? - -While the `/graphql` endpoint is easy and clean; rewrite rules, .htaccess configurations, or plugin conflicts can all break this endpoint. The `/index.php?graphql` endpoint can be a more resilient alternative to ensure your requests are still processed correctly. -If your application only talks to a WP instance(s) with pretty permalinks enabled and you trust that will not change, it’s safe to use the clean `/graphql` endpoint. - -If you don't know or don't trust the config to change, `/index.php?graphql` is recommended. WordPress is very flexible with URL routing, and even if your permalinks are enabled, the URL `/index.php?graphql` is still valid. \ No newline at end of file