graphql.md

   1 ---
   2 title: GraphQL
   3 layout: 2017/sheet
   4 updated: 2019-07-07
   5 category: API
   6 ---
   7
   8 ## Intro
   9
  10 ## Queries
  11 {: .-three-column}
  12
  13 ### Basic query
  14
  15 ```js
  16 { status }
  17 ```
  18
  19 #### ↓
  20
  21 ```js
  22 { status: 'available' }
  23 ```
  24 {: .-setup}
  25
  26 ### Nesting
  27
  28 ```js
  29 { hero { name height } }
  30 ```
  31
  32 #### ↓
  33
  34 ```js
  35 { hero:
  36     { name: "Luke Skywalker",
  37       height: 1.74 } }
  38 ```
  39 {: .-setup}
  40
  41 ### Lists
  42
  43 ```js
  44 { friends { name } }
  45 ```
  46
  47 #### ↓
  48
  49 ```js
  50 { friends:
  51     [ { name: "Luke Skywalker" },
  52       { name: "Han Solo" },
  53       { name: "R2D2" } ] }
  54 ```
  55 {: .-setup}
  56
  57 GraphQL queries look the same for both single items or lists of items.
  58
  59 ### Lookups
  60
  61 ```js
  62 {
  63   hero(id: "1000") { id name }
  64 }
  65 ```
  66
  67 #### ↓
  68
  69 ```js
  70 { hero:
  71     { id: "1000",
  72     { name: "Luke Skywalker" } }
  73 ```
  74 {: .-setup}
  75
  76 ### Aliases
  77
  78 ```js
  79 {
  80   luke: hero(id: "1000") { name }
  81   han: hero(id: "1001") { name }
  82 }
  83 ```
  84
  85 #### ↓
  86
  87 ```js
  88 { luke:
  89     { name: "Luke Skywalker" },
  90     han:
  91     { name: "Han Solo" } }
  92 ```
  93 {: .-setup}
  94
  95 ### Operation names and variables
  96
  97 #### Query
  98 ```js
  99 query FindHero($id: String!) {
 100   hero(id: $id) { name }
 101 }
 102 ```
 103
 104 Just to make things less ambiguous. Also, to use variables, you need an operation name.
 105
 106 #### Variables
 107
 108 ```js
 109 { id: '1000' }
 110 ```
 111
 112 ### Mutations
 113
 114 #### Query
 115
 116 ```js
 117 { createReview($review) { id } }
 118 ```
 119
 120 #### Variables
 121
 122 ```js
 123 { review: { stars: 5 } }
 124 ```
 125
 126 #### ↓
 127
 128 ```js
 129 { createReview: { id: 5291 } }
 130 ```
 131
 132 Mutations are just fields that do something when queried.
 133
 134 ### Multiple types
 135
 136 ```js
 137 {
 138   search(q: "john") {
 139     id
 140     ... on User { name }
 141     ... on Comment { body author { name } }
 142   }
 143 }
 144 ```
 145
 146 Great for searching.
 147
 148
 149 Over HTTP
 150 ---------
 151
 152 #### GET
 153
 154 ```js
 155 fetch('http://myapi/graphql?query={ me { name } }')
 156 ```
 157
 158 #### POST
 159
 160 ```js
 161 fetch('http://myapi/graphql', {
 162   body: JSON.stringify({
 163     query: '...',
 164     operationName: '...',
 165     variables: { ... }
 166   })
 167 })
 168 ```
 169
 170 Schema
 171 ------
 172 {: .-three-column}
 173
 174 ### Basic schemas
 175
 176 ```js
 177 type Query {
 178   me: User
 179   users(limit: Int): [User]
 180 }
 181
 182 type User {
 183   id: ID!
 184   name: String
 185 }
 186 ```
 187
 188 See: [sogko/graphql-shorthand-notation-cheat-sheet](https://raw.githubusercontent.com/sogko/graphql-shorthand-notation-cheat-sheet/master/graphql-shorthand-notation-cheat-sheet.png)
 189
 190 ### Built in types
 191
 192 #### Scalar types
 193
 194 | `Int` | Integer |
 195 | `Float` | Float |
 196 | `String` | String |
 197 | `Boolean` | Boolean |
 198 | `ID` | ID |
 199
 200 #### Type definitions
 201
 202 | `scalar` | Scalar type |
 203 | `type` | Object type |
 204 | `interface` | Interface type |
 205 | `union` | Union type |
 206 | `enum` | Enumerable type |
 207 | `input` | Input object type |
 208
 209 #### Type modifiers
 210
 211 | `String` | Nullable string |
 212 | `String!` | Required string |
 213 | `[String]` | List of strings |
 214 | `[String]!` | Required list of strings |
 215 | `[String!]!` | Required list of required strings |
 216
 217 ### Mutations
 218
 219 ```js
 220 type Mutation {
 221   users(params: ListUsersInput) [User]!
 222 }
 223 ```
 224
 225 ### Interfaces
 226
 227 ```js
 228 interface Entity {
 229   id: ID!
 230 }
 231
 232 type User implements Entity {
 233   id: ID!
 234   name: String
 235 }
 236 ```
 237
 238 ### Enums
 239
 240 ```js
 241 enum DIRECTION {
 242   LEFT
 243   RIGHT
 244 }
 245
 246 type Root {
 247   direction: DIRECTION!
 248 }
 249 ```
 250 {: data-line="1,2,3,4"}
 251
 252 ### Unions
 253
 254 ```js
 255 type Artist { ··· }
 256 type Album { ··· }
 257
 258 union Result = Artist | Album
 259
 260 type Query {
 261   search(q: String) [Result]
 262 }
 263 ```
 264 {: data-line="4"}
 265
 266 References
 267 ----------
 268
 269 - <http://graphql.org/learn/queries/>
 270 - <http://graphql.org/learn/serving-over-http/>