GraphQL API Wrapper for Wikipedia

This project is a GraphQL API wrapper for the Wikipedia API.

Author: Jordan Levesque - @KotaHusky

License: MIT

Table of Contents

• Project Requirements
• Usage
  • Installation
  • Run the server via local devserver
  • Run the server via Docker
  • Explore the GraphQL Sandbox
  • Querying the server
    • Example 1: Plain GraphQL Query
    • Example 2: Querying the server using curl
• GraphQL
  • Extending GraphQL
• Nx
  • Example Commands
• Future Improvements and Production Considerations
  • Corner Cases
  • Performance
  • Security
  • Reliability
  • Scalability & Extensibility
  • Best Practices
• References & Resources

Project Requirements

Usage

Installation

yarn install

Run the server via local devserver

yarn serve

Run the server via Docker

yarn serve:docker

or

make -f apps/Makefile docker-all

Explore the GraphQL Sandbox

Once the server is running, you can explore the GraphQL API using the Sandbox at http://localhost:4000/.

The Sandbox allows you to:

• View and reference the GraphQL schema
• Create, run, and manage GraphQL queries
• View schema diff (if logged in and enabled on Apollo Studio)

Querying the server

Example 1: Plain GraphQL Query

Here's an example query for the getWikipediaPageByMonth GraphQL query:

query GetWikipediaPageByMonth($title: String!, $targetMonth: String!) {
    getWikipediaPageByMonth(title: $title, targetMonth: $targetMonth) {
        title
        totalViews
    }
}

In this example, the query takes two variables: title and targetMonth. The getWikipediaPageByMonth field returns the title and totalViews fields for a given Wikipedia page.

Example 2: Querying the server using curl

Using curl, you can query the server like so:

curl --request POST \
  --url http://localhost:4000/ \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/8.2.0' \
  --data '{"query":"query GetWikipediaPageByMonth($title: String!, $targetMonth: String!) {\n  getWikipediaPageByMonth(title: $title, targetMonth: $targetMonth) {\n    title\n    totalViews\n  }\n}","operationName":"GetWikipediaPageByMonth","variables":{"title":"Husky","targetMonth":"2023-09"}}'

GraphQL

GraphQL is a query language for APIs that allows clients to request exactly the data they need, while enabling the server to aggregate data from multiple sources with a strongly-typed schema. See here for more information.

• Self-Documenting via strong types, docstrings, and Introspection
• No over- or under-fetching
• Easily extensible schema

TypeDefs in GraphQL are similar to interfaces in TypeScript. They define the shape of the data that can be queried from the GraphQL API.

Resolvers in GraphQL are functions that return data for a given field in the GraphQL schema.

Extending GraphQL

TypeDefs and Resolvers for a given schema subject are stored in .type.ts files in the src/graphql/types directory. The GraphQL schema is generated on server start using the makeExecutableSchema function from @graphql-tools/schema.

Nx

Nx is a set of extensible dev tools for monorepos and standalone projects. See here for more information.

• Create new projects, apps, libraries, and components with generators like nx g @nrwl/react:component my-component
• Run tasks only for affected projects with nx affected:test
• Cache results and run tasks in parallel for faster execution
• Enforce and visualize boundaries between projects with nx dep-graph

Example Commands

Perform a dry-run of a generating command with --dry-run

Create a new Nx workspace:

yarn create nx-workspace grow-therapy --package-manager=yarn --workspaceType=integrated --nx-cloud=false --preset=apps

Create a new Nx application:

yarn nx g @nx/node:application --name=api --bundler=esbuild --directory=apps --framework=express --docker=true --projectNameAndRootFormat=as-provided

Future Improvements and Production Considerations

Corner Cases

Handle cases where:

• the Wikipedia API returns an empty result for a given page, month, or both.
• the Wikipedia API returns an error.
• the Wikipedia API returns a result with a different schema than expected.
• the Wikipedia API enforces a rate limit.
• the GraphQL API recieves a request with an invalid query or variables.

Performance

• Add a cache layer to reduce the number of requests to the Wikipedia API. See here.
• Add a load balancer to handle multiple requests to the GraphQL API.
• Add query complexity analysis to prevent expensive queries from being executed. See here.

Security

• Add authentication and authorization for role-based access to GQL operations. See here.
• Add SSL termination to the GraphQL API. See here.
• Use organization docker images instead of public images.

Reliability

• Add logging to the GraphQL API. See here.
• Add full validation suite (lint, test, build) using Apollo Server's executeOperation and Nx's affected.
• Add CICD pipeline to build and deploy the GraphQL API via GitHub Actions.
• Add monitoring to the GraphQL API. See here.

Scalability & Extensibility

• Integrate with other data sources as needed.
• Share ownership by federating into a supergraph. See here.

Best Practices

• Familiarize team with the Principles of GraphQL. See here.

References & Resources

• Nx
• Express
• @graphql-tools
• Apollo Server
  • Modularized Schema
  • Express Middleware
• Docker