directives.graphql

# cache this kind of resource for an hour
type Person@cacheControl(maxAge: 3600) {
    id: ID!
    name: String!
    height: Int
    bio: String

	# cache the image field for a week
    picture: String @cacheControl(maxAge: 10080)

	# add an extra field, which tells if the current user favourited this Person
	# this will be cached for the current user session only
	userFavourite: Boolean! @cacheControl(scope: PRIVATE)
}

intro.graphql

# Schema definition
#
# Fist, we define a resource Type, called Person
type Person  {
	id: ID!
	# this is a Field of Scalar Type String,
	# the ! shows it cannot be null
	name: String!
	# this is a Field of Scalar Type Integer
	height: Int
	bio: String
	picture: String
}

# this resource Type has a relation with another resource Type
type Starship  {
	id: ID!
	name: String!
	model: String
	picture: String
	owner: Person    # this field will contain data of a Person type
}

# the root Query, every QraphQL service has one
# listing the resources available for fetching:
type Query {
	# will return with Person with
	# the ID passed in the argument
	Person(id: ID): Person

	# this query will return a list (array) of Persons,
	# default page is 1
	allPersons(page: Int = 1): [ Person ]

	# will return with Starship with
	# the ID passed in the argument
	Starship(id: ID): Starship
}


# Schemas for Mutations
#
# like the root Query, there is a root Mutation type,
# for every service, that shows what data can be mutated and how
type Mutation {

	# mutations can use your resource Types as schemas,
	# since they already define their fields and types

	# this can be away to create a Person,
	# but you might get lost in the parameters,
	# so I would advise against it
	addPerson(name: String!, height: Int, bio: String, picture: String ): Person
}


# create a new kind of Type instead, an Input Type!
# this defines a data schema that will be sent to the server
# as a new record, or record update
input CreatePerson {
	name: String!
	picture: String
	height: Int
	bio: String
}

# now the addPerson Mutation from earlier can be this
type Mutation {

	addPerson(person: CreatePerson): Person!

	# this Mutation returns a Person Type resource as a response
	# the new Person that has been created
}

queries_and_mutations.graphql

# Queries
#
# fetch some fields of a resource with an id
# this will return only the ID and the name of the Person
query PersonMinimal($id: ID) { # this is the name of the query
    Person(id: $id) {          # this is the actual resource you're getting
		id
		name
    }
}

# same resource type, but with all fields
query PersonFull($id: ID) {
    Person(id: $id) {
		id
		name
		picture
		bio
		height
    }
}

# get the list of Persons
# arguments will be passed in with the help of your client library
# in this case if the page argument is not present,
# the default value is 1
query PersonList($page: Int = 1) {
	allPersons(page: $page) {
		id
		name
		picture
	}
}

# get a Starship with its pilot Person!
# We only need the person's id, picture and name,
# we don't need height and full bio here.
# This is best part of GraphQL!
query getStarship($id: ID) {
	Starship(id: $id) {
		id
		name
		model
		picture
		owner { # here a Person type will be served
			id
			name
			picture
		}
	}
}


# lets have a mutation
# we'll use the CreatePerson Input Type that was defined in the schema
mutation UploadNewPerson($person: CreatePerson) {
  addPerson(person: $person) {
    name # we will use only the name from the newly created and returned Person entry
  }
}

# for this mutation, this parameter provides the new Person data
# it has to match the CreatePerson type scheme
{
  "person": {
    "name": "Kara Thrace",
    "picture": "https://img.url/kara.png",
    "height": 173
	}
}

react-graphql.jsx

const QUERY_PERSON_LIST = gql`
query PersonList($page: Int = 1) {
	allPersons(page: $page) {
		id
		name
		picture
	}
}
`

// same Query used with the Query Component

export default PersonListing = () => (
	<Query query={QUERY_PERSON_LIST}>
		{({ loading, error, data }) => {
			if (error) return <Error />
			if (loading || !data) return <Loading />

			return <PersonList people={data.allPersons} />
		}}
	</Query>
)

// Used with the graphql method

export default graphql(QUERY_PERSON_LIST, PersonList)