Rename Server::endpoint to Server::graphql_path (#1609)

This more accurately represents the behavior of the option which changes the path at which your Router will respond to GraphQL requests. The previous name gave the impression that it might be the full "endpoint" which it was not (again, just a path!) Closes #1606 Co-authored-by: Gary Pennington <gary@apollographql.com>
apollographql · Aug 26, 2022 · 162a777 · 162a777
1 parent 2c9ba04
commit 162a777
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 45 deletions.
diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
@@ -41,6 +41,21 @@ Terminating after logging the panic details is the best choice here.
 
 By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/1602
 
+### Rename the `endpoint` parameter to `graphql_path` ([#1606](https://github.com/apollographql/router/issues/1606))
+
+The `endpoint` parameter within the `server` portion of the YAML configuration has been renamed to `graphql_path` to more accurately reflect its behavior.
+
+If you used this option, the necessary change would look like:
+
+```diff
+- server:
+-   endpoint: /graphql
++ server:
++   graphql_path: /graphql
+```
+
+By [@abernix](https://github.com/abernix) in https://github.com/apollographql/router/pull/1609
+
 ### Remove `activate()` from the plugin API ([PR #1569](https://github.com/apollographql/router/pull/1569))
 
 Recent changes to configuration reloading means that the only known consumer of this API, telemetry, is no longer using it.

diff --git a/apollo-router/src/axum_http_server_factory.rs b/apollo-router/src/axum_http_server_factory.rs
@@ -90,15 +90,15 @@ where
     let cors = configuration.cors.clone().into_layer().map_err(|e| {
         ApolloRouterError::ServiceCreationError(format!("CORS configuration error: {e}").into())
     })?;
-    let graphql_endpoint = if configuration.server.endpoint.ends_with("/*") {
+    let graphql_path = if configuration.server.graphql_path.ends_with("/*") {
         // Needed for axum (check the axum docs for more information about wildcards https://docs.rs/axum/latest/axum/struct.Router.html#wildcards)
-        format!("{}router_extra_path", configuration.server.endpoint)
+        format!("{}router_extra_path", configuration.server.graphql_path)
     } else {
-        configuration.server.endpoint.clone()
+        configuration.server.graphql_path.clone()
     };
     let mut router = Router::<hyper::Body>::new()
         .route(
-            &graphql_endpoint,
+            &graphql_path,
             get({
                 let display_landing_page = configuration.server.landing_page;
                 move |host: Host, Extension(service): Extension<RF>, http_request: Request<Body>| {
@@ -212,7 +212,7 @@ impl HttpServerFactory for AxumHttpServerFactory {
             tracing::info!(
                 "GraphQL endpoint exposed at {}{} 🚀",
                 actual_listen_address,
-                configuration.server.endpoint
+                configuration.server.graphql_path
             );
             // this server reproduces most of hyper::server::Server's behaviour
             // we select over the stop_listen_receiver channel and the listener's
@@ -1271,7 +1271,7 @@ mod tests {
             .server(
                 crate::configuration::Server::builder()
                     .listen(SocketAddr::from_str("127.0.0.1:0").unwrap())
-                    .endpoint(String::from("/graphql"))
+                    .graphql_path(String::from("/graphql"))
                     .build(),
             )
             .build();
@@ -1340,7 +1340,7 @@ mod tests {
             .server(
                 crate::configuration::Server::builder()
                     .listen(SocketAddr::from_str("127.0.0.1:0").unwrap())
-                    .endpoint(String::from("/:my_prefix/graphql"))
+                    .graphql_path(String::from("/:my_prefix/graphql"))
                     .build(),
             )
             .build();
@@ -1409,7 +1409,7 @@ mod tests {
             .server(
                 crate::configuration::Server::builder()
                     .listen(SocketAddr::from_str("127.0.0.1:0").unwrap())
-                    .endpoint(String::from("/graphql/*"))
+                    .graphql_path(String::from("/graphql/*"))
                     .build(),
             )
             .build();
@@ -1628,7 +1628,7 @@ mod tests {
             .server(
                 crate::configuration::Server::builder()
                     .listen(SocketAddr::from_str("127.0.0.1:0").unwrap())
-                    .endpoint(String::from("/graphql/*"))
+                    .graphql_path(String::from("/graphql/*"))
                     .build(),
             )
             .build();

diff --git a/apollo-router/src/configuration/mod.rs b/apollo-router/src/configuration/mod.rs
@@ -262,10 +262,10 @@ pub(crate) struct Server {
     #[serde(default = "default_landing_page")]
     pub(crate) landing_page: bool,
 
-    /// GraphQL endpoint
+    /// The HTTP path on which GraphQL requests will be served.
     /// default: "/"
-    #[serde(default = "default_endpoint")]
-    pub(crate) endpoint: String,
+    #[serde(default = "default_graphql_path")]
+    pub(crate) graphql_path: String,
 
     /// healthCheck path
     /// default: "/.well-known/apollo/server-health"
@@ -291,7 +291,7 @@ impl Server {
         listen: Option<ListenAddr>,
         introspection: Option<bool>,
         landing_page: Option<bool>,
-        endpoint: Option<String>,
+        graphql_path: Option<String>,
         health_check_path: Option<String>,
         defer_support: Option<bool>,
         parser_recursion_limit: Option<usize>,
@@ -300,7 +300,7 @@ impl Server {
             listen: listen.unwrap_or_else(default_listen),
             introspection: introspection.unwrap_or_else(default_introspection),
             landing_page: landing_page.unwrap_or_else(default_landing_page),
-            endpoint: endpoint.unwrap_or_else(default_endpoint),
+            graphql_path: graphql_path.unwrap_or_else(default_graphql_path),
             health_check_path: health_check_path.unwrap_or_else(default_health_check_path),
             experimental_defer_support: defer_support.unwrap_or_else(default_defer_support),
             experimental_parser_recursion_limit: parser_recursion_limit
@@ -433,7 +433,7 @@ fn default_landing_page() -> bool {
     true
 }
 
-fn default_endpoint() -> String {
+fn default_graphql_path() -> String {
     String::from("/")
 }
 
@@ -806,32 +806,32 @@ pub(crate) fn validate_configuration(raw_yaml: &str) -> Result<Configuration, Co
     }
 
     // Custom validations
-    if !config.server.endpoint.starts_with('/') {
+    if !config.server.graphql_path.starts_with('/') {
         return Err(ConfigurationError::InvalidConfiguration {
-            message: "invalid 'server.endpoint' configuration",
+            message: "invalid 'server.graphql_path' configuration",
             error: format!(
                 "'{}' is invalid, it must be an absolute path and start with '/', you should try with '/{}'",
-                config.server.endpoint,
-                config.server.endpoint
+                config.server.graphql_path,
+                config.server.graphql_path
             ),
         });
     }
-    if config.server.endpoint.ends_with('*') && !config.server.endpoint.ends_with("/*") {
+    if config.server.graphql_path.ends_with('*') && !config.server.graphql_path.ends_with("/*") {
         return Err(ConfigurationError::InvalidConfiguration {
-            message: "invalid 'server.endpoint' configuration",
+            message: "invalid 'server.graphql_path' configuration",
             error: format!(
                 "'{}' is invalid, you can only set a wildcard after a '/'",
-                config.server.endpoint
+                config.server.graphql_path
             ),
         });
     }
-    if config.server.endpoint.contains("/*/") {
+    if config.server.graphql_path.contains("/*/") {
         return Err(
                 ConfigurationError::InvalidConfiguration {
-                    message: "invalid 'server.endpoint' configuration",
+                    message: "invalid 'server.graphql_path' configuration",
                     error: format!(
                         "'{}' is invalid, if you need to set a path like '/*/graphql' then specify it as a path parameter with a name, for example '/:my_project_key/graphql'",
-                        config.server.endpoint
+                        config.server.graphql_path
                     ),
                 },
             );
@@ -1021,35 +1021,35 @@ mod tests {
     }
 
     #[test]
-    fn bad_endpoint_configuration_without_slash() {
+    fn bad_graphql_path_configuration_without_slash() {
         let error = validate_configuration(
             r#"
 server:
-  endpoint: test
+  graphql_path: test
   "#,
         )
         .expect_err("should have resulted in an error");
-        assert_eq!(error.to_string(), String::from("invalid 'server.endpoint' configuration: 'test' is invalid, it must be an absolute path and start with '/', you should try with '/test'"));
+        assert_eq!(error.to_string(), String::from("invalid 'server.graphql_path' configuration: 'test' is invalid, it must be an absolute path and start with '/', you should try with '/test'"));
     }
 
     #[test]
-    fn bad_endpoint_configuration_with_wildcard_as_prefix() {
+    fn bad_graphql_path_configuration_with_wildcard_as_prefix() {
         let error = validate_configuration(
             r#"
 server:
-  endpoint: /*/test
+  graphql_path: /*/test
   "#,
         )
         .expect_err("should have resulted in an error");
-        assert_eq!(error.to_string(), String::from("invalid 'server.endpoint' configuration: '/*/test' is invalid, if you need to set a path like '/*/graphql' then specify it as a path parameter with a name, for example '/:my_project_key/graphql'"));
+        assert_eq!(error.to_string(), String::from("invalid 'server.graphql_path' configuration: '/*/test' is invalid, if you need to set a path like '/*/graphql' then specify it as a path parameter with a name, for example '/:my_project_key/graphql'"));
     }
 
     #[test]
     fn unknown_fields() {
         let error = validate_configuration(
             r#"
 server:
-  endpoint: /
+  graphql_path: /
 subgraphs:
   account: true
   "#,
@@ -1080,15 +1080,15 @@ unknown:
     }
 
     #[test]
-    fn bad_endpoint_configuration_with_bad_ending_wildcard() {
+    fn bad_graphql_path_configuration_with_bad_ending_wildcard() {
         let error = validate_configuration(
             r#"
 server:
-  endpoint: /test*
+  graphql_path: /test*
   "#,
         )
         .expect_err("should have resulted in an error");
-        assert_eq!(error.to_string(), String::from("invalid 'server.endpoint' configuration: '/test*' is invalid, you can only set a wildcard after a '/'"));
+        assert_eq!(error.to_string(), String::from("invalid 'server.graphql_path' configuration: '/test*' is invalid, you can only set a wildcard after a '/'"));
     }
 
     #[test]

diff --git a/...r/src/configuration/snapshots/apollo_router__configuration__tests__schema_generation.snap b/...r/src/configuration/snapshots/apollo_router__configuration__tests__schema_generation.snap
@@ -406,18 +406,13 @@ expression: "&schema"
         "listen": "127.0.0.1:4000",
         "introspection": true,
         "landing_page": true,
-        "endpoint": "/",
+        "graphql_path": "/",
         "health_check_path": "/.well-known/apollo/server-health",
         "experimental_defer_support": false,
         "experimental_parser_recursion_limit": 4096
       },
       "type": "object",
       "properties": {
-        "endpoint": {
-          "description": "GraphQL endpoint default: \"/\"",
-          "default": "/",
-          "type": "string"
-        },
         "experimental_defer_support": {
           "description": "Experimental @defer directive support default: false",
           "default": false,
@@ -430,6 +425,11 @@ expression: "&schema"
           "format": "uint",
           "minimum": 0.0
         },
+        "graphql_path": {
+          "description": "The HTTP path on which GraphQL requests will be served. default: \"/\"",
+          "default": "/",
+          "type": "string"
+        },
         "health_check_path": {
           "description": "healthCheck path default: \"/.well-known/apollo/server-health\"",
           "default": "/.well-known/apollo/server-health",

diff --git a/docs/source/configuration/overview.mdx b/docs/source/configuration/overview.mdx
@@ -240,19 +240,19 @@ server:
 
 By default, the router starts an HTTP server that exposes a `POST`/`GET` endpoint at path `/`.
 
-You can change this path by setting `server.endpoint`:
+You can change this path by setting `server.graphql_path`:
 
 ```yaml title="router.yaml"
 #
 # server: Configuration of the HTTP server
 #
 server:
-  # The exposed endpoint to answer to GraphQL queries
+  # The path for GraphQL execution
   # (Defaults to /)
-  endpoint: /graphql
+  graphql_path: /graphql
 ```
 
-The endpoint path must start with `/`.
+The path must start with `/`.
 
 Path parameters and wildcards are supported. For example: