From c83baf6efb3abb0faeb55d118324704f3ce2c1f2 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Sun, 10 Jan 2021 16:28:20 -0800 Subject: [PATCH] Editorial: s/server/service (#811) We use "server" and "service" in the spec interchangeably. With a few rare exceptions we mean "service". We also use this term slightly more often, so I've replaced nearly all cases of "server" with "service" `rg server | wc -l` - 44 `rg service | wc -l` - 55 One exception is "client-server" which is a recognizable term of art --- spec/Section 1 -- Overview.md | 24 ++++++++++++------------ spec/Section 2 -- Language.md | 2 +- spec/Section 3 -- Type System.md | 30 +++++++++++++++--------------- spec/Section 4 -- Introspection.md | 8 ++++---- spec/Section 5 -- Validation.md | 8 ++++---- spec/Section 6 -- Execution.md | 6 +++--- spec/Section 7 -- Response.md | 6 +++--- 7 files changed, 42 insertions(+), 42 deletions(-) diff --git a/spec/Section 1 -- Overview.md b/spec/Section 1 -- Overview.md index a2988ddcd..1072ab552 100644 --- a/spec/Section 1 -- Overview.md +++ b/spec/Section 1 -- Overview.md @@ -26,10 +26,10 @@ Which produces the resulting data (in JSON): ``` GraphQL is not a programming language capable of arbitrary computation, but is -instead a language used to query application servers that have +instead a language used to query application services that have capabilities defined in this specification. GraphQL does not mandate a -particular programming language or storage system for application servers that -implement it. Instead, application servers take their capabilities and map them +particular programming language or storage system for application services that +implement it. Instead, application services take their capabilities and map them to a uniform language, type system, and philosophy that GraphQL encodes. This provides a unified interface friendly to product development and a powerful platform for tool-building. @@ -47,39 +47,39 @@ GraphQL has a number of design principles: their way of thinking and requirements and builds the language and runtime necessary to enable that. - * **Strong-typing**: Every GraphQL server defines an application-specific + * **Strong-typing**: Every GraphQL service defines an application-specific type system. Queries are executed within the context of that type system. Given a query, tools can ensure that the query is both syntactically correct and valid within the GraphQL type system before execution, i.e. at - development time, and the server can make certain guarantees about the shape + development time, and the service can make certain guarantees about the shape and nature of the response. - * **Client-specified queries**: Through its type system, a GraphQL server + * **Client-specified queries**: Through its type system, a GraphQL service publishes the capabilities that its clients are allowed to consume. It is the client that is responsible for specifying exactly how it will consume those published capabilities. These queries are specified at field-level granularity. In the majority of client-server applications written - without GraphQL, the server determines the data returned in its various + without GraphQL, the service determines the data returned in its various scripted endpoints. A GraphQL query, on the other hand, returns exactly what a client asks for and no more. - * **Introspective**: GraphQL is introspective. A GraphQL server's type system + * **Introspective**: GraphQL is introspective. A GraphQL service's type system must be queryable by the GraphQL language itself, as will be described in this specification. GraphQL introspection serves as a powerful platform for building common tools and client software libraries. Because of these principles, GraphQL is a powerful and productive environment for building client applications. Product developers and designers building -applications against working GraphQL servers -- supported with quality tools -- -can quickly become productive without reading extensive documentation and with +applications against working GraphQL services—supported with quality tools—can +quickly become productive without reading extensive documentation and with little or no formal training. To enable that experience, there must be those -that build those servers and tools. +that build those services and tools. The following formal specification serves as a reference for those builders. It describes the language and its grammar, the type system and the introspection system used to query it, and the execution and validation engines with the algorithms to power them. The goal of this specification is to provide a foundation and framework for an ecosystem of GraphQL tools, client libraries, -and server implementations -- spanning both organizations and platforms -- that +and service implementations—spanning both organizations and platforms—that has yet to be built. We look forward to working with the community in order to do that. diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index ef4a4eddc..aa40aa94a 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -399,7 +399,7 @@ Argument[Const] : Name : Value[?Const] Fields are conceptually functions which return values, and occasionally accept arguments which alter their behavior. These arguments often map directly to -function arguments within a GraphQL server's implementation. +function arguments within a GraphQL service's implementation. In this example, we want to query a specific user (requested via the `id` argument) and their profile picture of a specific `size`: diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 26155f2d0..1981d71aa 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1,6 +1,6 @@ # Type System -The GraphQL Type system describes the capabilities of a GraphQL server and is +The GraphQL Type system describes the capabilities of a GraphQL service and is used to determine if a query is valid. The type system also describes the input types of query variables to determine if values provided at runtime are valid. @@ -346,7 +346,7 @@ promises to conform to ISO-8601. When querying a field of type `Time`, you can then rely on the ability to parse the result with an ISO-8601 parser and use a client-specific primitive for time. Another example of a potentially useful custom scalar is `Url`, which serializes as a string, but is guaranteed by -the server to be a valid URL. +the service to be a valid URL. ```graphql example scalar Time @@ -373,7 +373,7 @@ all built-in scalars must be omitted for brevity. **Result Coercion and Serialization** -A GraphQL server, when preparing a field of a given scalar type, must uphold the +A GraphQL service, when preparing a field of a given scalar type, must uphold the contract the scalar type describes, either by coercing the value or producing a field error if a value cannot be coerced or if coercion may result in data loss. @@ -383,21 +383,21 @@ expected return type. For example when coercing a field of type {Int} a boolean {123}. However if internal type coercion cannot be reasonably performed without losing information, then it must raise a field error. -Since this coercion behavior is not observable to clients of the GraphQL server, +Since this coercion behavior is not observable to clients of the GraphQL service, the precise rules of coercion are left to the implementation. The only -requirement is that the server must yield values which adhere to the expected +requirement is that the service must yield values which adhere to the expected Scalar type. GraphQL scalars are serialized according to the serialization format being used. There may be a most appropriate serialized primitive for each given scalar type, -and the server should produce each primitive where appropriate. +and the service should produce each primitive where appropriate. See [Serialization Format](#sec-Serialization-Format) for more detailed information on the serialization of scalars in common JSON and other formats. **Input Coercion** -If a GraphQL server expects a scalar type as input to an argument, coercion +If a GraphQL service expects a scalar type as input to an argument, coercion is observable and the rules must be well defined. If an input value does not match a coercion rule, a query error must be raised. @@ -425,7 +425,7 @@ that type to represent this scalar. Fields returning the type {Int} expect to encounter 32-bit integer internal values. -GraphQL servers may coerce non-integer internal values to integers when +GraphQL services may coerce non-integer internal values to integers when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning `1` for the floating-point number `1.0`, or returning `123` for the string `"123"`. In scenarios where coercion may lose @@ -460,7 +460,7 @@ should use that type to represent this scalar. Fields returning the type {Float} expect to encounter double-precision floating-point internal values. -GraphQL servers may coerce non-floating-point internal values to {Float} when +GraphQL services may coerce non-floating-point internal values to {Float} when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning `1.0` for the integer number `1`, or `123.0` for the string `"123"`. @@ -486,7 +486,7 @@ and that representation must be used here. Fields returning the type {String} expect to encounter UTF-8 string internal values. -GraphQL servers may coerce non-string raw values to {String} when reasonable +GraphQL services may coerce non-string raw values to {String} when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning the string `"true"` for a boolean true value, or the string `"1"` for the integer `1`. @@ -508,7 +508,7 @@ representation of the integers `1` and `0`. Fields returning the type {Boolean} expect to encounter boolean internal values. -GraphQL servers may coerce non-boolean raw values to {Boolean} when reasonable +GraphQL services may coerce non-boolean raw values to {Boolean} when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning `true` for non-zero numbers. @@ -532,14 +532,14 @@ across many formats ID could represent, from small auto-increment numbers, to large 128-bit random numbers, to base64 encoded values, or string values of a format like [GUID](https://en.wikipedia.org/wiki/Globally_unique_identifier). -GraphQL servers should coerce as appropriate given the ID formats they expect. +GraphQL services should coerce as appropriate given the ID formats they expect. When coercion is not possible they must raise a field error. **Input Coercion** When expected as an input type, any string (such as `"4"`) or integer (such as `4` or `-4`) input value should be coerced to ID as appropriate for the ID -formats a given GraphQL server expects. Any other input value, including float +formats a given GraphQL service expects. Any other input value, including float input values (such as `4.0`), must raise a query error indicating an incorrect type. @@ -1376,7 +1376,7 @@ enum Direction { **Result Coercion** -GraphQL servers must return one of the defined set of possible values. If a +GraphQL services must return one of the defined set of possible values. If a reasonable coercion is not possible they must raise a field error. **Input Coercion** @@ -1562,7 +1562,7 @@ like this: `pets: [Pet]`. Nesting lists is allowed: `matrix: [[Int]]`. **Result Coercion** -GraphQL servers must return an ordered list as the result of a list type. Each +GraphQL services must return an ordered list as the result of a list type. Each item in the list must be the result of a result coercion of the item type. If a reasonable coercion is not possible it must raise a field error. In particular, if a non-list is returned, the coercion should fail, as this diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 889db030e..2735417f1 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -1,12 +1,12 @@ # Introspection -A GraphQL server supports introspection over its schema. This schema is queried +A GraphQL service supports introspection over its schema. This schema is queried using GraphQL itself, creating a powerful platform for tool-building. Take an example query for a trivial app. In this case there is a User type with three fields: id, name, and birthday. -For example, given a server with the following type definition: +For example, given a service with the following type definition: ```graphql example type User { @@ -70,7 +70,7 @@ underscores. All types in the introspection system provide a `description` field of type `String` to allow type designers to publish documentation in addition to -capabilities. A GraphQL server may return the `description` field using Markdown +capabilities. A GraphQL service may return the `description` field using Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). Therefore it is recommended that any tool that displays `description` use a CommonMark-compliant Markdown renderer. @@ -411,7 +411,7 @@ Fields ### The __Directive Type -The `__Directive` type represents a Directive that a server supports. +The `__Directive` type represents a Directive that a service supports. Fields diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index b855de085..7e7238ed5 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -1439,8 +1439,8 @@ input object field is optional. **Explanatory Text** -GraphQL servers define what directives they support. For each -usage of a directive, the directive must be available on that server. +GraphQL services define what directives they support. For each +usage of a directive, the directive must be available on that service. ### Directives Are In Valid Locations @@ -1456,9 +1456,9 @@ usage of a directive, the directive must be available on that server. **Explanatory Text** -GraphQL servers define what directives they support and where they support them. +GraphQL services define what directives they support and where they support them. For each usage of a directive, the directive must be used in a location that the -server has declared support for. +service has declared support for. For example the following query will not pass validation because `@skip` does not provide `QUERY` as a valid location. diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 236bff77a..f6e735bb4 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -162,7 +162,7 @@ If the operation is a subscription, the result is an event stream called the "Response Stream" where each event in the event stream is the result of executing the operation for each new event on an underlying "Source Stream". -Executing a subscription creates a persistent function on the server that +Executing a subscription creates a persistent function on the service that maps an underlying Source Stream to a returned Response Stream. Subscribe(subscription, schema, variableValues, initialValue): @@ -221,7 +221,7 @@ must receive no more events from that event stream. Supporting subscriptions is a significant change for any GraphQL service. Query and mutation operations are stateless, allowing scaling via cloning of GraphQL -server instances. Subscriptions, by contrast, are stateful and require +service instances. Subscriptions, by contrast, are stateful and require maintaining the GraphQL document, variables, and other context over the lifetime of the subscription. @@ -354,7 +354,7 @@ of Field Execution for more about this behavior. Normally the executor can execute the entries in a grouped field set in whatever order it chooses (normally in parallel). Because the resolution of fields other than top-level mutation fields must always be side effect-free and idempotent, -the execution order must not affect the result, and hence the server has the +the execution order must not affect the result, and hence the service has the freedom to execute the field entries in whatever order it deems optimal. For example, given the following grouped field set to be executed normally: diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index f51fb5982..bacd39323 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -1,7 +1,7 @@ # Response -When a GraphQL server receives a request, it must return a well-formed -response. The server's response describes the result of executing the requested +When a GraphQL service receives a request, it must return a well-formed +response. The service's response describes the result of executing the requested operation if successful, and describes any errors encountered during the request. @@ -28,7 +28,7 @@ if set, must have a map as its value. This entry is reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents. -To ensure future changes to the protocol do not break existing servers and +To ensure future changes to the protocol do not break existing services and clients, the top level response map must not contain any entries other than the three described above.