What is an API?

What is a RESTful API?

• Statelessness: The server does not store any information or context about the client between requests, meaning the request has everything it needs for the server to process it.
• Client-server separation: The client and server are completely separate, meaning the server parses requests and produces responses, whereas the client generates requests and determines how to display responses to a user.
• Resource identifiers: REST APIs use Uniform Resource Identifiers (URIs) to address resources (also known as endpoints).

What are the problems with REST?

• Multiple requests: RESTful APIs separate their endpoints using resource identifiers, meaning if we want resources from different places, we need to send request to multiple endpoints, which increases load times.
• Over fetching data: Because of client-server separation, the client has no say in what data they will get when they hit a particular endpoint. This can result in the client receiving more data than they actually need, which again will increase load times.
• Unknown structure: For the same reason as above, when a client requests data from an endpoint, it’s possible that they’ll have no knowledge of how that data is structured until they actually request the data. This can result in negative developer experience.

What is GraphQL?

• Single endpoint: GraphQL is served over HTTP via a single endpoint, allowing us to fetch any data required from this endpoint using queries and mutations (as we’ll see later).
• Request what is needed: With GraphQL the client specifies what resources they need and GraphQL returns only these resources. No more, no less.
• Typed schema: With GraphQL we create a schema which fully defines all available data and its types, which means we know exactly what we can request before we actually request it.

Basic REST API Setup

• GET /pokemon: responds to a GET request returning all details of all Pokemon in the db
• GET /pokemon/id: responds to a GET request returning all details of a single Pokemon from its id
• POST /pokemon: responds to a POST request that creates a new Pokemon in the db

// src/routes/pokemon.ts
import { Router } from 'express';
import prisma from '../prisma';

const router = Router();

router.get("/pokemon", async (req, res, next) => {
  const pokemon = await prisma.pokemon.findMany();
	res.json(pokemon);
});

router.get("/pokemon/:id", async (req, res, next) => {
  const pokemon = await prisma.pokemon.findFirst({ where: { id: req.params.id }});
	if (pokemon) {
		res.json(pokemon);
	} else {
		res.status(404).json({ message: "Pokemon not found" });
	}
});

router.post("/pokemon", async (req, res, next) => {
  const { data } = req.body;
  await prisma.pokemon.create({ data });
  res.status(201);
});

export default router;

// index.ts
import express from 'express';
import Pokemon from './src/routes/pokemon';

const app = express();

app.listen(3000, () => console.log(`App listening on port 3000`));

app.use(Pokemon);

Migrating to GraphQL

• Use the first endpoint to fetch all details of all Pokemon, then filter the resulting data on the frontend to contain only the names. This would result in a massive over fetch of data (there are 801 Pokemon in our database!)
• Add a new endpoint that returns only the names of Pokemon. This would take additional developer effort, especially considering in a production app we’d also want to add test files. And then what happens if we want to access only a different Pokemon property? We want to avoid adding an endpoint for each one!

yarn add graphql class-validator type-graphql reflect-metadata apollo-server-express apollo-server-core typegraphql-prisma graphql-scalars graphql-fields @types/graphql-fields tslib
yarn add -D express-graphql

{
  "compilerOptions": {
    "target": "es2018",
    "module": "commonjs",
    "lib": ["es2018", "esnext.asynciterable"],
    "strict": true,
    "esModuleInterop": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "strictPropertyInitialization": false
  }
}

// src/schema/pokemon/pokemon.type.ts
import { Field, ObjectType } from "type-graphql";

@ObjectType()
export class Pokemon {
  @Field()
  id: number;   

  @Field()
  name: string;

  @Field()
  pokedex_number: number;

  @Field()
  attack: number;

  @Field()
  defense: number;

  @Field()
  hp: number;

  @Field()
  sp_attack: number;

  @Field()
  sp_defense: number;

  @Field()
  speed: number;
}

// src/schema/pokemon/pokemon.resolver.ts
import { Arg, Query, Resolver } from "type-graphql";
import { Pokemon } from "./pokemon.type";
import prisma from "../../prisma";

@Resolver()
export class PokemonResolver {
  @Query(() => [Pokemon])
  async allPokemon(): Promise<Pokemon[]> {
		const pokemon = await prisma.pokemon.findMany();
		return pokemon;
  }

  @Query(() => Pokemon)
  async pokemon(
    @Arg("id") id: number,
  ): Promise<Pokemon | null> {
    const pokemon = await prisma.pokemon.findFirst({ where: { id }});
    if (pokemon) {
      return pokemon;
    }
    return null;
  }

	@Mutation(() => Boolean)
  async addPokemon(@Arg("data") newPokemon: PokemonInput): Promise<boolean> {
    await prisma.pokemon.create({ data: newPokemon });
    return true;
  }
}

import express from "express";
import http from 'http';
import { buildSchema } from "type-graphql";
import { PokemonResolver } from "./src/schema/pokemon/pokemon.resolver";
import { ApolloServer } from 'apollo-server-express';
import { ApolloServerPluginDrainHttpServer } from "apollo-server-core";

const bootstrap = async () => {
  const schema = await buildSchema({
    resolvers: [PokemonResolver],
  });
  const app = express();
  const httpServer = http.createServer(app);

  const server = new ApolloServer({
    schema,
    plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
  });

  await server.start();
  server.applyMiddleware({
    app,
    path: '/graphql'
  });
  await new Promise<void>(resolve => httpServer.listen({ port: 3000 }, resolve));
  console.log(`🚀 Server ready at http://localhost:3000${server.graphqlPath}`);
};

bootstrap();