😴

Connect to a REST API

Overview

This guide will walk you through the process of connecting Graphweaver to a REST API. We'll use a sample REST API for illustration purposes, but you can adapt the steps to connect to your own API. An example of a REST implementation can be found in our Graphweaver Repo.

Prerequisites

Before you begin, ensure that you have the following prerequisites:

  • Node.js 18 or greater installed
  • pnpm version 8 or greater installed

Step 1: Project Initialisation

Create a new Graphweaver project by running the following command:

npx graphweaver@latest init

Follow the prompts to set up your project. Provide a name when prompted, and select the REST API when asked about Graphweaver backends.

Install the dependencies in your project.

cd your-project-name
pnpm i

Ensure your graphweaver instance starts with:

pnpm start

Step 2: Configure REST API Connection

Create a file named .env in your project directory and configure the connection details for your REST API:

REST_API_URL=https://your-rest-api-url.com
API_KEY=your-api-key

Replace https://your-rest-api-url.com with the actual URL of your REST API, and your-api-key with the API key if required.

Step 3: Create Your REST entities

Define your backend entity by extending the BaseEntity from the graphweaver-rest package and decorating your fields with the @Field decorator. backend/entities/rest/user.ts

import { BaseEntity, Field } from '@exogee/graphweaver-rest';

export class User extends BaseEntity {
	@Field()
	name!: string;

	@Field()
	url!: string;
}

Create your GraphQL entity from the backend entity.

backend/schema/user/entity.ts

import { GraphQLEntity, SummaryField, Field, ID, ObjectType } from '@exogee/graphweaver';
import { User as RestUser } from '../../entities';

@ObjectType('User')
export class User extends GraphQLEntity<RestUser> {
	public dataEntity!: RestUser;

	@Field(() => ID)
	id!: string;

	@SummaryField()
	@Field(() => String)
	name!: string;
}

Step 4: Create your resolver

Now we’ll hook up our connection to the REST API. First let’s create a generic fetch function to access our base rest url. backend/rest-client.ts

import got from 'got';

const baseUrl = process.env.REST_BASE_URL;

export const fetch = async <T>(path: string) => {
	return got.get(`${baseUrl}${path}`).json<T[]>();
};

This will allow us to access the base rest url and pass in a specific endpoint. Now let’s create our User resolver. This UserResolver will extend the RestBackendProvider and will implement the methods of the RestBackendProvider. We implement the find method by calling our fetch function with our chosen endpoint. In this case our Users are returned by the /people end point. Once we have the results of the REST call, we can transform the data any way we like before returning it to the Graphweaver GraphQL API. However, the results must match the GraphQL entity we defined above.

import { createBaseResolver, Resolver } from '@exogee/graphweaver';
import { AccessorParams, RestBackendProvider } from '@exogee/graphweaver-rest';
import url from 'url';

import { User as RestUser } from '../../entities';
import { User } from './entity';
import { fetch } from '../../rest-client';
import { inMemoryFilterFor } from '@exogee/graphweaver-helpers';

@Resolver((of) => User)
export class UserResolver extends createBaseResolver<User, RestUser>(
	User,
	new RestBackendProvider('User', {
		find: async ({ filter }: AccessorParams) => {
			const results = await fetch<RestUser>(`/people`);
			// Apply any data transformation here 
			return results;
		},
	})
) {}

Conclusion

Congratulations! You've successfully connected Graphweaver to a REST API. You can now explore and interact with the data from your API using GraphQL queries.

Feel free to customise this guide based on the specifics of your REST API and Graphweaver project configuration. For more information and connecting a second data source, refer to the Graphweaver Documentation.

Exogee