Skip to content

Commit 8a562a7

Browse files
unicodeveloperpeggyrayzis
unicodeveloper
authored and
peggyrayzis
committed
Add more information and improve words based on peggy's and jake's review 🔥
1 parent ed38216 commit 8a562a7

1 file changed

Lines changed: 82 additions & 37 deletions

File tree

‎docs/source/resources/graphql-glossary.md‎

Lines changed: 82 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -4,52 +4,56 @@ description: A comprehensive list of important GraphQL words and acronyms
44
---
55

66

7-
We have put together a glossary of words and acronyms that you might hear or come across frequently in GraphQL land. Every developer and GraphQL enthusiast should be able to easily look up a particular term here when referenced in specs, reference guides, READMEs and within a codebase.
7+
When you start diving into the GraphQL ecosystem, you'll probably encounter some unfamiliar terms and phrases along the way. To help you on your journey, we've defined some of the most common GraphQL vocabulary here in this handy cheat sheet.
88

99

1010
<h2 id="Apollo">Apollo</h2>
11-
<p>A set of tools for building GraphQL apps. Some of these tools are Apollo Client (best way to use GraphQL to build Client apps), Apollo Server (for building GraphQL servers), Engine (performance monitoring and tracing), etc.</p>
11+
<p>An open-source implementation of GraphQL that helps you manage data between the cloud and your UI. The Apollo platform is pluggable into your existing architecture and features production-ready tooling across the stack ([Server](https://www.apollographql.com/docs/apollo-server/getting-started.html), [Client](https://www.apollographql.com/docs/react/), and [Engine](https://www.apollographql.com/docs/engine/)).</p>
1212

1313
<h2 id="automatic-persisted-queries">Automatic Persisted Queries (APQ) </h2>
14-
<p> A technique for improving GraphQL network performance by reducing request size over the wire. </p>
14+
<p> A technique for improving GraphQL network performance with zero build-time configuration by reducing request size over the wire. A smaller signature reduces bandwidth utilization and speeds up client loading times. Apollo Server allows implementation of [Automatic Persisted Queries (APQ)](https://www.apollographql.com/docs/guides/performance.html#automatic-persisted-queries). </p>
1515

1616
<h2 id="argument">Argument</h2>
17-
<p>A parameter or set of key-value pair passed to fields in a schema to filter out results sent back from the server to the client.</p>
17+
<p>A set of key-value pairs attached to a specific field. Arguments can be literal values or variables.</p>
18+
19+
```js
20+
{
21+
human(id: "200") {
22+
weight(unit: "pounds")
23+
height
24+
}
25+
}
26+
```
1827

1928
<h2 id="alias">Alias</h2>
2029
<p>An alternative name given to the result of a field to avoid conflicts during data fetching.</p>
2130

22-
<h2 id="data-source">Data Source</h2>
23-
<p>A new utility and pattern for fetching and caching data from REST API endpoints. When layering GraphQL over REST APIs, data sources provides the ability to have a resource cache that saves and shares data easily across multiple GraphQL servers.</p>
24-
2531
```js
26-
const { RESTDataSource } = require('apollo-datasource-rest');
27-
28-
class MoviesAPI extends RESTDataSource {
29-
constructor() {
30-
super();
31-
this.baseURL = 'https://movies-api.example.com/';
32-
}
33-
34-
async getMovie(id) {
35-
return this.get(`movies/${id}`);
32+
{
33+
admin: users(role: admin) {
34+
id
35+
firstname
36+
lastname
3637
}
37-
38-
async getMostViewedMovies(limit = 10) {
39-
const data = await this.get('movies', {
40-
per_page: limit,
41-
order_by: 'most_viewed',
42-
});
43-
return data.results;
38+
managers: users(role: manager) {
39+
id
40+
firstname
41+
lastname
4442
}
4543
}
4644
```
4745

48-
<h2 id="deferred-query">Deferred Query</h2>
46+
<h2 id="data-source">Data Source</h2>
47+
<p>A class that encapsulates fetching data from a particular service, with built-in support for caching, deduplication, and error handling.</p>
48+
49+
<h2 id="deferred-query">Deferred query</h2>
50+
<p>A declaration prefixed with an @ character that encapsulates programming logic for query execution on the client or server. There are built-in such as @skip, @include and custom directives. It can be used for features such as authentication, incremental data loading, etc.</p>
51+
52+
<h2 id="directive">Directive</h2>
4953
<p>A declaration prefixed with an @ character that encapsulates programming logic for query execution on the client or server. There are built-in such as @skip, @include and custom directives. It can be used for features such as authentication, incremental data loading, etc.</p>
5054

5155
<h2 id="docstring">Docstring</h2>
52-
<p>A technique for providing metadata to a GraphQL Document. It can used for describing types, fields and arguments.</p>
56+
<p>It is used for providing descriptions of types, fields and arguments. It adds metadata to a GraphQL document. Docstrings show up in the documentation panel inside GraphQL playground and GraphiQL.</p>
5357

5458
```js
5559
"""
@@ -73,19 +77,33 @@ type User {
7377
<h2 id="document">Document</h2>
7478
<p>A file or request string that contains one or multiple definitions of a GraphQL type system and can be interpreted by a GraphQL execution engine.</p>
7579

76-
<h2 id="extensions">Extensions </h2>
77-
<p></p>
80+
<h2 id="extensions">Extensions</h2>
81+
<p>Special fields in the Graphql response that allows you to attach extra metadata. [Apollo tracing](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-tracing) is an example of an extension. </p>
7882

7983

8084
<h2 id="field">Field</h2>
81-
<p>A node in a GraphQL Object type that makes up a Schema. It is a unit of data.</p>
85+
<p>A unit of data you are asking for in a Schema, which ends up as a field in your JSON response data.</p>
8286

8387

8488
<h2 id="fragment">Fragment</h2>
85-
<p>A selection set that can be reused in multiple query operations.</p>
89+
<p>A selection set that can be reused in multiple query operations. A [GraphQL fragment](https://www.apollographql.com/docs/react/advanced/fragments.html) is a shared piece of query logic.</p>
90+
91+
```js
92+
fragment UserData on User {
93+
id: ID!
94+
firstName: String!
95+
lastName: String!
96+
}
97+
98+
query getUsers {
99+
allUsers {
100+
...UserData
101+
}
102+
}
103+
```
86104

87105
<h2 id="gql-function">gql function</h2>
88-
<p>A JavaScript template literal tag that parses GraphQL queries.</p>
106+
<p>A [JavaScript template literal tag](https://github.com/apollographql/graphql-tag) that parses GraphQL queries into an abstract syntax tree (AST).</p>
89107

90108
```js
91109
const typeDefs = gql`
@@ -98,16 +116,25 @@ const typeDefs = gql`
98116
```
99117

100118
<h2 id="graphql-playground">GraphQL Playground</h2>
101-
<p>An in-browser IDE for GraphQL development and workflow. Added benefits exist such as theme change, automatic schema reloading, HTTP headers configuration, query history and GraphQL subscription support.</p>
119+
<p>An in-browser IDE for GraphQL development and workflow. Added benefits exist such as theme change, automatic schema reloading, HTTP headers configuration, query history and GraphQL subscription support. In addition, it comes [out-of-the-box in Apollo Server 2](https://www.apollographql.com/docs/apollo-server/features/graphql-playground.html).</p>
102120

103121
<h2 id="graphiql">GraphiQL</h2>
104-
<p>An in-browser IDE for GraphQL development. The first-ever GraphQL IDE released by Facebook.</p>
122+
<p>An in-browser IDE for GraphQL development.</p>
105123

106124
<h2 id="introspection">Introspection</h2>
107125
<p>A technique to provide detailed information about a GraphQL API's schema. Types and fields used in introspection are prefixed with "__" two underscores.</p>
108126

109127
<h2 id="mutation">Mutation</h2>
110-
<p>An operation for creating, modifying and destroying data. A fetch operation happens immediately after the write.</p>
128+
<p>An operation for creating, modifying and destroying data.</p>
129+
130+
```js
131+
mutation AddTodo($type: String!) {
132+
addTodo(type: $type) {
133+
id
134+
type
135+
}
136+
}
137+
```
111138

112139
<h2 id="normalization">Normalization</h2>
113140
<p>A technique for transforming default GraphQL responses into a specific desired format.</p>
@@ -150,11 +177,29 @@ type User {
150177
<h2 id="operation-name">Operation name</h2>
151178
<p>A name for a single query, mutation, or subscription. Identifying a query or mutation by name is very useful for logging and debugging when something goes wrong in a GraphQL server.</p>
152179

180+
```js
181+
mutation AddTodo($type: String!) {
182+
addTodo(type: $type) {
183+
id
184+
type
185+
}
186+
}
187+
188+
query getHuman {
189+
human(id: "200") {
190+
weight(unit: "pounds")
191+
height
192+
}
193+
}
194+
```
195+
196+
`AddTodo` and `getHuman` are names for the mutation and query operation respectively.
197+
153198
<h2 id="partial-query-caching">Partial query caching</h2>
154199
<p>A technique for caching inputs to GraphQL queries. This type of caching ensures that if the query is slightly different but with the same inputs, those inputs can simply be retrieved from the cache instead of fetching data again from the backend. It is implemented in Apollo Server 2 as Data Source caching.</p>
155200

156201
<h2 id="query">Query</h2>
157-
<p>An operation that makes a GET request to a GraphQL service requesting for some data. It's better known as a read-only fetch operation.</p>
202+
<p>A read-only fetch operation to request data from a GraphQL service.</p>
158203

159204
<h2 id="query-colocation">Query colocation</h2>
160205
<p>A practice of placing a GraphQL query in the same location as the app component's view logic.</p>
@@ -182,7 +227,7 @@ export const queryComponent = `const DogPhoto = ({ breed }) => (
182227
```
183228

184229
<h2 id="query-whitelisting">Query whitelisting</h2>
185-
<p>A technique for preventing unwanted attacks by maintaining a list of approved queries that are allowed in your application. Any query not present in the list that is run against the server will not be allowed. [Automatic Persisted Queries](../guides/performance.html#automatic-persisted-queries) is a tool by Apollo that enables query whitelisting and persisted queries.</p>
230+
<p>A technique for preventing unwanted attacks by maintaining a list of approved queries that are allowed in your application. Any query not present in the list that is run against the server will not be allowed. [Automatic Persisted Queries](../guides/performance.html#automatic-persisted-queries) is a feature of Apollo Server 2 that enables query whitelisting and persisted queries.</p>
186231

187232
<h2 id="resolver">Resolver</h2>
188233
<p>A function that connects schema fields and types to various backends. It can retrieve or write data from either an SQL, a No-SQL, graph database, a micro-service or a REST API.</p>
@@ -201,7 +246,7 @@ export const queryComponent = `const DogPhoto = ({ breed }) => (
201246

202247

203248
<h2 id="schema-registry">Schema registry</h2>
204-
<p>A central database that enables schema registration, tracking of detailed schema changes e.g. types added, fields added, fields deprecated and checking out previous versions of schema.</p>
249+
<p>A central database that enables schema registration, tracking of detailed schema changes e.g. types added, fields added, fields deprecated and looking up previous versions of schema.</p>
205250

206251

207252
<h2 id="schema-versioning">Schema versioning</h2>

0 commit comments

Comments
 (0)