Show Menu
Cheatography
  1. Home >
  2. Programming >

API GraphQL Cheat Sheet (DRAFT) by

API Cheat Sheet for GraphQL

This is a draft cheat sheet. It is a work in progress and is not finished yet.

Mutations: OnChan­geR­esponse

{{noshy}}{
  "id": "Query",
  "data": {
    "generalQueryName": [... UPDATED DATA ...], // For queries without pagination/filters
    "-anotherQueryName": null, // For queries with pagination and/or filter
  }
}
- QueryName there is top level properties on your 
Query
type.
- You should list all top level QueryNames that may be affected (data could be changed) after applying mutation

Entity / ID's

id:
ID!
Main Entity id
 
userId:
ID!
Foreign Entity id
 
deletedByAdminId:
ID
Foreign Entity id with modifier
 
deletedByAdminName:
String
Foreign Entity field with modifier
- 
deletedBy
- is modifi­er/­action
- 
Admin
- is Foreign Type/E­ntity name
- 
Id
/
Name
- is Foreign Entity field

Filters: Date / Time

startTime:
DateTime
 
endTime:
DateTime
 
startDate:
Date
 
endDate:
Date
 
createdTimeFrom:
DateTime
 
createdTimeTo:
DateTime

Know how to deprecate

type MyType {
  id: ID!
  oldField: String @deprecated(reason: "oldField is deprecated. Use newField instead.")
  newField: String
  anotherField: String @deprecated
}
For example 
userId
in the 
User
Type could be deprec­ated, because there is 
id
have been added
https:­//s­pec.gr­aph­ql.o­rg­/Ju­ne2­018­/#s­ec-­-de­pre­cated

Non Nullable

Ensure that all fields that always should have a value is marked as Non Nullable (!) in response
For example Nullable Boolean have a three state which makes a confusion.
Only really optional fields, may be Nullable

Group Fields

type GeoPoint {
  lat: Float!
  lon: Float!
}


type Address {
  street: String
  city: String
  country: String!
  geo: GeoPoint
}

type User {
  address: Address
}
Do not shy to group related fields.
That simplify readin­g/u­nde­rst­anding of API, reusing the same Fragments, and write common utilities to work with that
  

Filters: Nullab­ility

isActive:
Boolean
 
startTime:
DateTime
 
siteId:
ID!
Required filter field is Not Nullable
 
limitNames:
[LimitName!]
No Nullable Entities inside array
- Fields is Nullable, because 
null
means that we opt-out filter
- Empty array is also means that we opt-out filter

Pagination

totalPages:
NonNegativeInt!
0 – ∞
 
totalElements:
NonNegativeInt!
0 – ∞
 
page:
PositiveInt!
1 – ∞
 
size:
PositiveInt!
1 – ∞
 
isFirst:
Boolean!
 
isLast:
Boolean!
 
content:
[SomeEntity!]!
If there is no entities - Empty Array is pretty good!

Transl­ations

period: "­P1Y­"
 
period­Name: "One Year"
Transl­ation for 
period
values
 
type: TypeEnum
"­TEM­POR­ATY­" | "­PER­MAN­ENT­"
 
typeName: "­Tem­por­aty­"
Tranlation for 
TypeEnum
values

Boolean Fields

isActive:
Boolean!
 
isDeleted:
Boolean!
 
hasContent:
Boolean!
- Always start boolean fields with 
is
/ 
has
prefix. (That's just a good practice)
- Do not forget that Nullable Boolean have a three state: 
true
, 
false
and 
"I'm not sure"
, don't do that!

Use specific Scalar types

Bad
Good
 
country:
String!
 
country:
Country!
 
pageContent:
String!
 
pageContent:
HTML!
 
currency:
String!
 
currency:
Currency!
 
metadata:
String!
 
metadata:
JSON!
 
value:
String!
 
value:
Duration!
 
addressType:
Int!
 
addressType:
AddressTypeEnum!
- That allow you to implement validation for corres­ponding type once, and reuse it everyw­here.
- For FE that also allows to validate the types, and improving readab­ility and unders­tanding of API