Learn how to use GraphQL with Angular using Apollo (Step by Step)

The Network-Protocol

First, let’s take a look at how both look like a network-level.

REST REST is fully utilizing the HTTP-protocol.

That means, that request are either get, post, put or delete requests.

For that, it uses an object-oriented endpoint approach, that is modeled using the URL of the resource.

 http://example.com/api/blogposts

Depending on the chosen request-method, the request has a different effect.

Get-request are typically used for read-only operations, while post creates a new instance of the chosen object.

Put is used to update an object and delete should delete an object.

For advanced requests, a combination of sub-routes and URL-parameter is used. For example, if we would want to fetch only 10 blog-posts, we would use an URL-parameter like this:

 http://example.com/api/blogposts?limit=10

The response of the server is typically a JSON-document.

GraphQL Often times, GraphQL endpoints use HTTP, as well, but the query language is not limited to that.

It is also possible to use for example the websocket-protocol to transmit the requests over the network.

For a better comparison, let’s assume we are using a GraphQL API via HTTP.

GraphQL APIs typically have only one endpoint.

 http://example.com/api

All request are sent to that endpoint, independent from the requested object-type (blog-posts) or the desired crud (create, read, update, delete) operation.

They also only use either the HTTP-get or HTTP-post method (one per API) to send the request.

To specify a request, we use the query language itself. The language looks a little bit like JSON, but its syntax is different.

Here is the same example from above for querying 10 blog-posts.

 {
	blogposts(limit: 10) {
		title
		thumbnail
		content
	}
}

Again, we are using the limit parameter, to limit the number of returned objects.

But while REST typically returns the full object with every field, we have to specify which fields of our object we want to receive using GraphQL.

The response of a GraphQL is a JSON-document.

Overfetching & Underfetching

The above shows example one of the great improvements of GraphQL over REST very nicely. Let’s take a look at the reason why.

Again, using our blog-post example, we could have a front-page showing all our blog-post and a detail-page, showing the actual content of each post.

The requirements to the API of both pages are quite different.

While the front-page only requires the title and the thumbnail of each post, the detail page requires all attributes of the post, including the relatively large content.

The problem with a REST-API is a problem called overfetching. Because we can not easily specify which attributes of our blog-posts we want to receive, our blog-application would have to fully download all blog-post to display the front-page.

This results in huge loading times and a lot of unnecessary transferred data.

GraphQL, on the other hand, takes an approach called underfetching. This is exactly what we have seen in the last example. If not explicitly stated, a GraphQL-API does not return any fields of an object. That way, we only get the attributes of our blog-post that we really need.

The request of our front-page could look something like this, only requesting the title and the thumbnail of all posts.

 {
	blogposts(limit: 10) {
		title
		thumbnail
	}
}

The detail-page, on the other hand, is requesting one specific post (e.g. with the id: 1) with all available attributes.

 {
	blogpost(id: 1) {
		title
		thumbnail
		content
	}
}

Setting up a new Node.js Project

To get started, create a new directory for our new project. You can call it whatever you want.

Next, we initialize a new npm-project by opening the console inside of our new directory and executing the following command:

 npm init

It will ask you some questions. Answer them and hit enter, until the setup has finished.

Afterwards, create a new JavaScript file and call it server.js.

We will also need a file named schema.js.

Now go ahead and open both files with your favorite IDE/Editor.

External Dependencies

Before we start coding, we need to install some external dependencies first. That shouldn’t take too long.

 npm i --save express express-graphql graphql graphql-tools

Here we go! Ready to write some code?

GraphQL Types

To create the new type, open the schema.js file and add a new variable like this:

let typeDefs = `
type blogpost {
    id: String!
    title: String!
    thumbnail: String
    content: String
}`

The variable typeDefs will contain all our types for our API. Here we have created the type “blog-post”. Each blog-post has a set of fields.

Every field has a type, as well. The type is defined after the colon. In this example, all fields are of the type “String”.

content: String

You can also define if a field is required. To do so, we add an exclamation mark behind the type. For example:

 id: String!
 

Input Types

GraphQL differentiates between types for reading and for input purposes. These types are called Input Types and are defined with the input keyword. This is useful because some fields are filled by the server and therefore don’t need to be fed in.

In our example, the id of a blog-post can’t be defined by the user but is generated by the server automatically. Therefore our input type does not contain a filed called id.

Because we want our API to accept new blog-posts, as well, we add an input called blog-post to our type-definition:

let typeDefs = `
type blogpost {
    id: String!
    title: String!
    thumbnail: String
    content: String
}
 
input blogpostInput {
    title: String!
    thumbnail: String
    content: String
}`

The types inside of that new input type are defined in the same way as a normal type.

Query

The query-type is the root-type of all queries of your API. Inside of that Query-type, we define methods, that can be called via the API. For our example, we want to be able to query for one or for all blog-posts. Because of that, we will need to define two methods inside the query-type.

The definition of query-methods looks quite similar to normal Typescript methods.

 type Query {
    blogposts(limit: Int): [blogpost]
    blogpost(id: String!): blogpost
}

The parameters of the method, as well as the return type, are typed in GraphQL. To define an array of a type we place the type in brackets. Notice that we are using our newly created type “blog-post” here. Also, notice that the type “Query” has to be named exactly like this.

Let’s add the query-type to our type-definition:

let typeDefs = `
type blogpost {
    id: String!
    title: String!
    thumbnail: String
    content: String
}
 
input blogpostInput {
    title: String!
    thumbnail: String
    content: String
}
 
type Query {
    blogposts(limit: Int): [blogpost]
    blogpost(id: String!): blogpost
}`

Mutations

The queries we defined above are all read only. That means we can use them to get blogposts, but not to upload new ones. That is what mutations are for.

Just like input-types to types are mutations related to queries.

Here we define a method to create a new blog-post:

 type Mutation {
    addBlogpost(post: blogpostInput!): blogpost
}

We are using our new input-type as parameter because every parameter has to be either a native type (String, Int, …) or an input-type.

Afterwards, we add the mutation to our type-definition, as well.

let typeDefs = `
type blogpost {
    id: String!
    title: String!
    thumbnail: String
    content: String
}
 
input blogpostInput {
    title: String!
    thumbnail: String
    content: String
}
 
type Query {
    blogposts(limit: Int): [blogpost]
    blogpost(id: String!): blogpost
}
 
type Mutation {
    addBlogpost(post: blogpostInput!): blogpost
}
`

Our type-definition is now complete. Go ahead and add methods to update or delete a post if you like! Would you place them into Query or Mutation?

Setting up a new Angular Project

For demonstration purposes, let’s create a new angular-cli application.

 ng new graphql-example

Afterward, we need to install some external dependencies. Open a terminal in the application directory and type:

 npm install apollo-angular apollo-angular-link-http apollo-client apollo-cache-inmemory graphql-tag graphql --save

Integrating Apollo into Angular

Next, we need to set up the Apollo client. Therefore we need to add some modules to our new app.module.

Furthermore, we need to initialize Apollo in the module’s constructor.

Please replace the URL with the actual URL of your GraphQL server.

import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { FormsModule } from '@angular/forms'
 
import { AppComponent } from './app.component'
import { HelloComponent } from './hello.component'
 
import { HttpClientModule } from '@angular/common/http'
import { ApolloModule, Apollo } from 'apollo-angular'
import { HttpLinkModule, HttpLink } from 'apollo-angular-link-http'
import { InMemoryCache } from 'apollo-cache-inmemory'
 
@NgModule({
  imports: [
    BrowserModule,
    FormsModule,
    HttpClientModule,
    ApolloModule,
    HttpLinkModule,
  ],
  declarations: [AppComponent, HelloComponent],
  bootstrap: [AppComponent],
})
export class AppModule {
  constructor(apollo: Apollo, httpLink: HttpLink) {
    apollo.create({
      link: httpLink.create({ uri: 'http://localhost:3000/graphql' }),
      cache: new InMemoryCache(),
    })
  }
}

Afterward, we can use Apollo anywhere in our app using dependency injection.

Here is an example querying all blog-posts and their title and printing them to the console.

import { Component } from '@angular/core'
import { Apollo } from 'apollo-angular'
import gql from 'graphql-tag'
 
@Component({
  selector: 'my-app',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent {
  constructor(apollo: Apollo) {
    apollo
      .query({
        query: gql`
          {
            query {
              blogposts {
                title
              }
            }
          }
        `,
      })
      .subscribe(console.log)
  }
}

Feel free to turn this component into something useful…