Skip to main contentCarbon Design System

3. Using APIs

This step takes our static components and populates them with data from the GitHub GraphQL API – loading states and all. We’ll be displaying Carbon repository information in a data table.

Preview

The GitHub GraphQL API is very well documented, and even though the focus of this tutorial isn’t learning and using GraphQL, it’s a great opportunity to fetch Carbon-related data for this Carbon tutorial.

To do so, we’ll be using Apollo Client, the front-end component of the Apollo Platform. Apollo provides several open source tools for using GraphQL throughout your application’s stack. Apollo Client is a sophisticated GraphQL client that manages data and state in an application.

A preview of what you will build (see repositories page):

Fork, clone and branch

This tutorial has an accompanying GitHub repository called carbon-tutorial-angular that we’ll use as a starting point for each step. If you haven’t forked and cloned that repository yet, and haven’t added the upstream remote, go ahead and do so by following the step 1 instructions.

Branch

With your repository all set up, let’s check out the branch for this tutorial step’s starting point.

git fetch upstream
git checkout -b angular-step-3 upstream/angular-step-3

Build and start app

Install the app’s dependencies:

npm install

Then, start the app:

npm start

You should see something similar to where the previous step left off. Stop your app with CTRL-C and let’s get everything installed.

Install dependencies

We’ll shortcut this using the Angular CLI, if you’d like more information head over to Angular Apollo Installation for details.

Install the following

  • apollo-client - package containing everything you need to set up Apollo Client
  • graphql - parses your GraphQL queries
  • apollo-angular - Apollo integration for Angular

Using the command:

ng add [email protected]
ng lint --fix
src/tsconfig.app.json
"lib": [
  "es2016",
  "dom",
  "esnext.asynciterable"
],
src/typings.d.ts
declare var module: {
  id: string,
};

Create access token

You’ll need a personal access token from your GitHub account in order to make requests to the GitHub API. Check out this guide to see how to get one.

When you get to the scope/permissions step, you can leave them all unchecked. We don’t need any special permissions, we just need access to the public API.

Once you have your token, we need to put it in a place where we can use it in our app. When your application is being built and developed, our app will parse environmental variables in any environment file and make them available.

​

src/environment/environment.ts
export const environment = {
  production: false,
  githubPersonalAccessToken: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
};

Go ahead and start your app with npm start, or, if your app is running, you’ll need to restart it to get access to this token.

Connect to Apollo

We need to import the environment at the top of every file that we decide to use it in:

import { environment } from '../environments/environment';

Next, make your client by providing a URI for the GitHub GraphQL API as well as an authorization header using the environmental variable you just added to environment.ts.

src/app/graphql.module.ts
import { HttpHeaders } from '@angular/common/http';


const uri = 'https://api.github.com/graphql'; // <-- add the URL of the GraphQL server here
export function createApollo(httpLink: HttpLink) {
  return {
    link: httpLink.create({
      uri,
      headers: new HttpHeaders({
        Authorization: `Bearer ${environment.githubPersonalAccessToken}`,

Fetch data

Imports

Add the following import at the top of repo-table.component.ts:

src/app/repositories/repo-table/repo-table.component.ts
import { Apollo } from 'apollo-angular';
import gql from 'graphql-tag';

Query

Next we’ll assemble our GraphQL query to fetch only the data we need from the GraphQL API. We’ll do this using the gql helper we just imported. The gql helper lets you write GraphQL queries using interpolated strings (backticks) in JavaScript.

You can use GitHub’s explorer tool to write and test your own queries. Try copying the query below and experiment with changing the properties. You can also click the “Docs” button in the top right of the explorer to view all of the available data and query parameters.

If you’d like some more information regarding writing queries, we recommend Apollo’s documentation on this topic.

First, we will add a private apollo parameter of type Apollo to the constructor to get access to the Apollo service.

src/app/repositories/repo-table/repo-table.component.ts
constructor(private apollo: Apollo) { }

Next, we will fetch the data in ngOnInit(). Add the following code right below the model.header declaration:

src/app/repositories/repo-table/repo-table.component.ts
this.apollo.watchQuery({
  query: gql`
    query REPO_QUERY {
      # Let's use carbon as our organization
      organization(login: "carbon-design-system") {
        # We'll grab all the repositories in one go. To load more resources
        # continuously, see the advanced topics.
        repositories(first: 75, orderBy: { field: UPDATED_AT, direction: DESC }) {
          totalCount

Custom data

Our last column in the data table will be a comma-separated list of repository and home page links, so let’s create a custom cell template.

The column will have two values (url and homepageUrl) and will have the structure of an unordered list. If the repository does not have a home page URL, only render the repository link.

src/app/repositories/repo-table/repo-table.component.html
<ng-template #linkTemplate let-data="data">
  <ul style="display: flex">
    <li>
      <a ibmLink [href]="data.github">Github</a>
    </li>
    <li *ngIf="data.homepage">
      <span>&nbsp;|&nbsp;</span>
      <a ibmLink [href]="data.homepage">HomePage</a>
    </li>
src/app/repositories/repo-table/repo-table.component.ts
@ViewChild('linkTemplate', null)
protected linkTemplate: TemplateRef<any>;

Now let’s create a function that transforms row data to our expected header keys. Notice how we’re using our new linkTemplate to generate the value of the links key in each row.

src/app/repositories/repo-table/repo-table.component.ts
prepareData