From 11a1950f2dfe8e4cf49c64712e6031d6d6b47a98 Mon Sep 17 00:00:00 2001 From: Laurin Quast Date: Thu, 14 Jul 2022 18:57:38 +0200 Subject: [PATCH 1/4] initial glossary draft --- docs/glossary.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/glossary.md diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..0fcd8ef --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,88 @@ +# Glossary + +### Type Merging + +The process of combining multiple GraphQL schemas (graphs) into a single GraphQL schema (graph). + +### Schema Stitching + +The process of creating a single gateway from multiple underlying GraphQL services (**Subschema**), that orchestrates and delegates requests to the corresponding GraphQL services using The Guild’s graphql-tools/stitching libraries. Stitching supports all methods of type merging (**Subschema Directive-based Type Merging** or **Programmatic/Config Gateway-based Type Merging**) and thus also supports **Apollo Federation.** + +### Apollo Federation + +An implementation of **Subschema Directive-based Type Merging** that is defined by the Apollo Federation Specification. GraphQL schemas (**Apollo Federation Subgraph**s) are composed of a single GraphQL schema (**Apollo Federated Graph**) on a Gateway level (**Apollo Federation Gateway**). + +### “The Graph” + +Branding used by Apollo for describing all their libraries and products. + +> [...] the graph is a unified representation of all your data, services, and digital capabilities. The graph enables app developers to delete thousands of lines of boilerplate code, move fast without waiting on backend teams, and keep features consistent across web and mobile platforms + +Source: [https://www.apollographql.com/](https://www.apollographql.com/) (2022/02/24) +> + +### ****Apollo Graph Platform**** + +Branding used by Apollo for describing their open-source products. + +> ****The Apollo Graph Platform**** +The leading open-source GraphQL implementation with 17M downloads per month and the only end-to-end cloud management solution for GraphQL. + +Source: [https://www.apollographql.com/](https://www.apollographql.com/) (2022/02/24) +> + +### Apollo Federated Graph + +An implementation of Type Merging. The result of combining multiple Apollo federation Subgraphs is an Apollo Federated Graph. The Apollo Federated Graph is usually exposed via an Apollo Federation Gateway or Apollo Federation compatible gateway (e.g. graphql-mesh). + +### Apollo Federation Subgraph ([Link](https://www.apollographql.com/docs/federation/subgraphs/)) + +A service that exposes a GraphQL schema that is consumed by a gateway in order to create a federated graph. The services schema uses directive annotations on types and fields as a hint for a gateway on how it should combine the services schema with the schema of the other Apollo federation subgraphs. A Apollo Federation Subgraph is a GraphQL schema with Apollo Federation schema directives. Also See **Subschema**. + +### Apollo Federated Graph ([Link](https://www.apollographql.com/docs/federation/)) + +The process of composing multiple Apollo Subgraphs into one schema, usually via a Gateway. + +### Apollo Studio + +A schema registry for registering and validating Apollo federation subgraphs. + +### Apollo Federation Gateway + +A gateway that usually uses a schema registry (Apollo Studio) for fetching the apollo subgraph configurations. It is the entry point for incoming GraphQL requests. It analyzes the incoming operations, builds a query plan in order to find the quickest way of retrieving all the data from the apollo federation subgraphs, and then executes that plan. + +The approach of combining multiple GraphQL services into a unified GraphQL Graph on a Gateway using meta-information applied on the individual GraphQL services schema definitions. + +### Subschema + +A Subschema is a GraphQL schema that is used in a type merging contexts, such as in Apollo federation or Schema Stitching for. In Apollo federation, a Subschema is often called a Apollo Federation Subgraph. + +### Subschema Directive-based Type Merging + +The process of applying type merging on the Gateway using the directive meta-information exposed on the consumed GraphQL services (**Subschemas** as done by **Apollo Federation** or **Schema Stitching**. + +### Programmatic/Config Gateway-based Type Merging + +A method of Type Merging where the **Subschemas** do not expose any information on how they can be merged. Instead, the rules are defined on the Gateway, either as code or a configuration file. + +### Hybrid Type Merging + +A mix of both **Subschema Directive-based Type Merging** and **Programmatic/Config Gateway-based Type Merging**. + +### GraphQL Mesh + +A library maintained by The Guild that is capable of transforming a single or many **data sources** and **services** (GraphQL API, REST API, SQL Database) into a GraphQL schema. In the case of multiple data sources or services, Mesh uses Schema Stitching for doing Type Merging of the GraphQL subschemas that were the results of the transform. + +### Data Source + +A “dumb” service or database that exposes raw data. Often a data source is consumed by a service, for reading and/or persisting business logic state. + +It is hard to define a border between Data Source and Service. E.g. a PostgreSQL database could be considered a data source. If the PostgreSQL database uses database triggers for applying business logic constraints it could be considered a **Service** instead. The boundaries are fluid. + +### Service + +A service uses a data source and exposes processed data, that models a business logic flow. A data source can evolve into service over time. + +### GraphQL Hive + +A GraphQL schema registry and workflow tool maintained by The Guild that is compatible with any **type of merging** workflow. From becb82cf6f815f531ce661c8a6919d7d629ee272 Mon Sep 17 00:00:00 2001 From: Laurin Quast Date: Thu, 4 Aug 2022 09:40:19 +0200 Subject: [PATCH 2/4] sort names + replace type emrging term with schema composition --- docs/glossary.md | 139 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 94 insertions(+), 45 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 0fcd8ef..c6bfa01 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,88 +1,137 @@ # Glossary -### Type Merging - -The process of combining multiple GraphQL schemas (graphs) into a single GraphQL schema (graph). - -### Schema Stitching +### Apollo Federated Graph ([Link](https://www.apollographql.com/docs/federation/)) -The process of creating a single gateway from multiple underlying GraphQL services (**Subschema**), that orchestrates and delegates requests to the corresponding GraphQL services using The Guild’s graphql-tools/stitching libraries. Stitching supports all methods of type merging (**Subschema Directive-based Type Merging** or **Programmatic/Config Gateway-based Type Merging**) and thus also supports **Apollo Federation.** +The process of composing multiple Apollo Subgraphs into one schema, usually via +a Gateway. An implementation of Schema composition. The result of composing +multiple Apollo federation Subgraphs is a Apollo Federated Graph. The Apollo +Federated Graph is usually exposed via an Apollo Federation Gateway +(apollo/gateway; apollo-router) or Apollo Federation compatible gateway (e.g. +graphql-mesh). ### Apollo Federation -An implementation of **Subschema Directive-based Type Merging** that is defined by the Apollo Federation Specification. GraphQL schemas (**Apollo Federation Subgraph**s) are composed of a single GraphQL schema (**Apollo Federated Graph**) on a Gateway level (**Apollo Federation Gateway**). +An implementation of **Subschema Directive-based Schema compositions** that is +defined by the Apollo Federation Specification. GraphQL schemas (**Apollo +Federation Subgraph**s) are composed of a single GraphQL schema (**Apollo +Federated Graph**) on a Gateway level (**Apollo Federation Gateway**). -### “The Graph” +### Apollo Federation Gateway -Branding used by Apollo for describing all their libraries and products. +A gateway that usually uses a schema registry (e.g. Apollo Studio or GraphQL +Hive) for fetching the apollo subgraph configurations. It is the entry point for +incoming GraphQL requests. It analyzes the incoming operations, builds a query +plan in order to find the quickest way of retrieving all the data from the +apollo federation subgraphs, and then executes that plan. -> [...] the graph is a unified representation of all your data, services, and digital capabilities. The graph enables app developers to delete thousands of lines of boilerplate code, move fast without waiting on backend teams, and keep features consistent across web and mobile platforms +The approach of combining multiple GraphQL services into a unified GraphQL Graph +on a Gateway using meta-information applied on the individual GraphQL services +schema type definitions. -Source: [https://www.apollographql.com/](https://www.apollographql.com/) (2022/02/24) -> +### Apollo Federation Subgraph ([Link](https://www.apollographql.com/docs/federation/subgraphs/)) -### ****Apollo Graph Platform**** +A service that exposes a GraphQL schema that is consumed by a gateway in order +to create a federated graph. The services schema uses directive annotations on +types and fields as a hint for a gateway on how it should combine the services +schema with the schema of the other Apollo federation subgraphs. A Apollo +Federation Subgraph is a GraphQL schema with Apollo Federation schema +directives. Also See **Subschema**. + +### Apollo Graph Platform Branding used by Apollo for describing their open-source products. -> ****The Apollo Graph Platform**** -The leading open-source GraphQL implementation with 17M downloads per month and the only end-to-end cloud management solution for GraphQL. +> The leading open-source GraphQL implementation with 17M downloads per month +> and the only end-to-end cloud management solution for GraphQL. Source: +> [https://www.apollographql.com/](https://www.apollographql.com/) (2022/02/24) -Source: [https://www.apollographql.com/](https://www.apollographql.com/) (2022/02/24) -> +### Apollo Studio -### Apollo Federated Graph +A schema registry for registering and validating Apollo federation subgraphs. -An implementation of Type Merging. The result of combining multiple Apollo federation Subgraphs is an Apollo Federated Graph. The Apollo Federated Graph is usually exposed via an Apollo Federation Gateway or Apollo Federation compatible gateway (e.g. graphql-mesh). +### Data Source -### Apollo Federation Subgraph ([Link](https://www.apollographql.com/docs/federation/subgraphs/)) +A “dumb” service or database that exposes raw data. Often a data source is +consumed by a service, for reading and/or persisting business logic state. -A service that exposes a GraphQL schema that is consumed by a gateway in order to create a federated graph. The services schema uses directive annotations on types and fields as a hint for a gateway on how it should combine the services schema with the schema of the other Apollo federation subgraphs. A Apollo Federation Subgraph is a GraphQL schema with Apollo Federation schema directives. Also See **Subschema**. +It is hard to define a border between Data Source and Service. E.g. a PostgreSQL +database could be considered a data source. If the PostgreSQL database uses +database triggers for applying business logic constraints it could be considered +a **Service** instead. The boundaries are fluid. -### Apollo Federated Graph ([Link](https://www.apollographql.com/docs/federation/)) +### GraphQL Hive -The process of composing multiple Apollo Subgraphs into one schema, usually via a Gateway. +A GraphQL schema registry and workflow tool maintained by The Guild that is +compatible with any **type of merging** workflow. -### Apollo Studio +### GraphQL Mesh -A schema registry for registering and validating Apollo federation subgraphs. +A library maintained by The Guild that is capable of transforming a single or +many **data sources** and **services** (GraphQL API, REST API, SQL Database) +into a GraphQL schema. In the case of multiple data sources or services, Mesh +uses Schema Stitching for doing Schema Composition of the GraphQL subschemas +that were the results of the transform. -### Apollo Federation Gateway +### Hybrid Schema Composition -A gateway that usually uses a schema registry (Apollo Studio) for fetching the apollo subgraph configurations. It is the entry point for incoming GraphQL requests. It analyzes the incoming operations, builds a query plan in order to find the quickest way of retrieving all the data from the apollo federation subgraphs, and then executes that plan. +A mix of both **Subschema Directive-based Schema Composition** and +**Programmatic/Config Gateway-based Schema Composition**. -The approach of combining multiple GraphQL services into a unified GraphQL Graph on a Gateway using meta-information applied on the individual GraphQL services schema definitions. +### Nadel ([Link](https://github.com/atlassian-labs/nadel)) -### Subschema +> Nadel is a Kotlin library to combine several GraphQL services together. This +> is achieved by combining several underlying GraphQL services (schemas) into +> one schema (overall schema). The main purpose of this library is to power a +> GraphQL gateway which serves as the entry point for executing requests across +> different services while presenting one GraphQL API. -A Subschema is a GraphQL schema that is used in a type merging contexts, such as in Apollo federation or Schema Stitching for. In Apollo federation, a Subschema is often called a Apollo Federation Subgraph. +### Schema Composition -### Subschema Directive-based Type Merging +The process of composing multiple GraphQL schemas (**Subschema**) into a single +GraphQL schema. -The process of applying type merging on the Gateway using the directive meta-information exposed on the consumed GraphQL services (**Subschemas** as done by **Apollo Federation** or **Schema Stitching**. +### “The Graph” -### Programmatic/Config Gateway-based Type Merging +Branding used by Apollo for describing all their libraries and products. -A method of Type Merging where the **Subschemas** do not expose any information on how they can be merged. Instead, the rules are defined on the Gateway, either as code or a configuration file. +> [...] the graph is a unified representation of all your data, services, and +> digital capabilities. The graph enables app developers to delete thousands of +> lines of boilerplate code, move fast without waiting on backend teams, and +> keep features consistent across web and mobile platforms -### Hybrid Type Merging +Source: [https://www.apollographql.com/](https://www.apollographql.com/) +(2022/02/24) -A mix of both **Subschema Directive-based Type Merging** and **Programmatic/Config Gateway-based Type Merging**. +### Programmatic/Config Gateway-based Schema Composition -### GraphQL Mesh +A method of Schema Composition where the **Subschemas** do not expose any +information on how they can be composed. Instead, the rules are defined on the +Gateway, either as code or via a configuration file. -A library maintained by The Guild that is capable of transforming a single or many **data sources** and **services** (GraphQL API, REST API, SQL Database) into a GraphQL schema. In the case of multiple data sources or services, Mesh uses Schema Stitching for doing Type Merging of the GraphQL subschemas that were the results of the transform. +### Schema Stitching -### Data Source +The process of creating a single gateway from multiple underlying GraphQL +services (**Subschema**), that orchestrates and delegates requests to the +corresponding GraphQL services using The Guild’s graphql-tools/stitching +libraries. Stitching supports all methods of Schema Composition (**Subschema +Directive-based Schema Composition** or **Programmatic/Config Gateway-based +Schema Composition**), including **Apollo Federation.** (Subschema +Directive-based schema composition) -A “dumb” service or database that exposes raw data. Often a data source is consumed by a service, for reading and/or persisting business logic state. +### Service -It is hard to define a border between Data Source and Service. E.g. a PostgreSQL database could be considered a data source. If the PostgreSQL database uses database triggers for applying business logic constraints it could be considered a **Service** instead. The boundaries are fluid. +A service uses a data source and exposes processed data, that models a business +logic flow. A data source can evolve into service over time. -### Service +### Subschema -A service uses a data source and exposes processed data, that models a business logic flow. A data source can evolve into service over time. +A Subschema is a GraphQL schema that is used in a schema composition contexts, +such as in Apollo federation or Schema Stitching for. In Apollo federation, a +Subschema is often called a Apollo Federation Subgraph. A composite schema +itself can be a subschema in another composite schema. -### GraphQL Hive +### Subschema Directive-based Schema Composition -A GraphQL schema registry and workflow tool maintained by The Guild that is compatible with any **type of merging** workflow. +The process of applying schema composition on the Gateway using the directive +meta-information exposed on the consumed **Subschemas** (usually GraphQL HTTP +APIs/services) as done by **Apollo Federation** or **Schema Stitching**. From a511f6fc2469ba8a6f68b623aedf5239e2da84db Mon Sep 17 00:00:00 2001 From: Laurin Quast Date: Thu, 4 Aug 2022 09:47:35 +0200 Subject: [PATCH 3/4] apply feedback from https://github.com/graphql/composite-schemas-wg/pull/34#discussion_r921701888 --- docs/glossary.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index c6bfa01..ba2d843 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -59,6 +59,14 @@ database could be considered a data source. If the PostgreSQL database uses database triggers for applying business logic constraints it could be considered a **Service** instead. The boundaries are fluid. +# Global Object Identification + +Pattern of having global unique IDs between all Object Types (entities), usually +on a field with the name `id` and the field type `ID!`. + +- [Global Object Identification (graphql.org)](https://graphql.org/learn/global-object-identification/) +- [GraphQL Global Object Identification Specification (relay.dev)](https://relay.dev/graphql/objectidentification.htm) + ### GraphQL Hive A GraphQL schema registry and workflow tool maintained by The Guild that is @@ -85,6 +93,28 @@ A mix of both **Subschema Directive-based Schema Composition** and > GraphQL gateway which serves as the entry point for executing requests across > different services while presenting one GraphQL API. +### Nautilus ([Link](https://github.com/nautilus/gateway)) + +> A library and standalone service that composes your GraphQL APIs into one +> endpoint. + +Uses these +[merge strategies](https://github.com/nautilus/gateway/blob/master/docs/mergingStrategies.md) +and one interface type to compose subschemas (see **Node interface**). + +### Node interface + +The [Global Object +Identification][https://graphql.org/learn/global-object-identification/] +[spec][https://relay.dev/graphql/objectidentification.htm] defines a `Node` +interface, which enables composition if shared types implement it. +[Nautilus Gateway](https://github.com/nautilus/gateway) is one such +implementation. + +[global object identification]: + https://graphql.org/learn/global-object-identification/ +[relay-goi-spec]: (https://relay.dev/graphql/objectidentification.htm) + ### Schema Composition The process of composing multiple GraphQL schemas (**Subschema**) into a single From 60a87e36757a63da6b44822b3bd4ef8af2e9db7a Mon Sep 17 00:00:00 2001 From: Laurin Quast Date: Thu, 4 Aug 2022 09:50:26 +0200 Subject: [PATCH 4/4] add paragraph for describing the implications of this document --- docs/glossary.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index ba2d843..cc3c013 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,5 +1,9 @@ # Glossary +This glossary serves as a foundation for having a common wording and language. +The motivation behind this document was the many different namings and, hence, +the resulting communication issues when talking about schema composition. + ### Apollo Federated Graph ([Link](https://www.apollographql.com/docs/federation/)) The process of composing multiple Apollo Subgraphs into one schema, usually via