Skip to content

Latest commit

 

History

History
137 lines (84 loc) · 5.38 KB

Generating REST API with init.md

File metadata and controls

137 lines (84 loc) · 5.38 KB
Raw

Generating the REST API with init()

After generateGqlQueryFiles() is executed once, init() can be executed to create REST routes at runtime.

In this example, we'll use Apollo Link to connect via HTTP to our GraphQL server which runs on localhost (however this could be any type GraphQL server, running locally or remote.)

Using Apollo Link with fetch is the simplest way to connect GraphQL2REST to an existing GraphQL server.

For example:

const path = require('path');
const { schema } = require('./myGraphQLSchema.js'); // a GraphQLSchema object
const GraphQL2REST = require('graphql2rest');


const { execute, makePromise } = require('apollo-link');
const { createHttpLink } = require('apollo-link-http');
const fetch = require('node-fetch');

const express = require('express');
const app = express();

const gqlServerUri = 'http://localhost:3000/api/graphql'; // our existing GraphQL server

const link = createHttpLink({ uri: gqlServerUri, fetch });

/* GraphQL2REST execute function using apollo-link. Invokes GraphQL operation against gqlServerUri via node-fetch */
const executeGqlLink = (operation) => {
      return makePromise(execute(link, operation));
};

const GQL_FILES_FOLDER = path.resolve(__dirname,'./gqlFilesFolder'); // folder previously generated by generateGqlQueryFiles()

const gql2restOptions = {
	apiPrefix: '/api', //sets the API base path url
	manifestFile: path.resolve(__dirname,'./api-manifest.json'), //pathname of manifest file. Default is ./manifest.json
	gqlGeneratorOutputFolder: GQL_FILES_FOLDER  //.gql files folder
};

const restRouter = GraphQL2REST.init(schema, executeGqlLink, gql2restOptions);

// restRouter now has our REST API attached
app.use('/', restRouter);

Now the following REST API is mounted and active (based on the manifest file described earlier):

GET /api/users

GET /api/users/{userId}

POST /api/users

PATCH /api/users/{userId}

DELETE /api/users/{userId}


The init() function

init() takes two mandatory parameters: your GraphQL schema and the GraphQL server execute function (whatever your specific GraphQL server implementation provides, or an Apollo Link function).

GraphQL2REST.init(
      schema: GraphQLSchema,
      executeFn: Function,

      options?: Object,
      formatErrorFn?: Function,
      formatDataFn?: Function,
      expressRouter?: Function)

schema is a GraphQLSchema object. You can generate this object using buildSchema() function from the graphql package.

executeFn is a function that, similarly to Apollo Link, accepts a single object with { query, variables, context, operationName } arguments.

If you want to use another kind of GraphQL execution function, which receives different arguments, you can wrap that GraphQL 'execute' function with executeFn, and map the arguments so that the final execution function receives the right arguments and values (see the example under /examples).


options can be used to define specific settings (see below). If undefined, default values will be used.

formatErrorFn is an optional function to custom format GraphQL error responses. It receives (response, statusCode) arguments where response is the original response from GraphQL and statusCode is the final HTTP status code. It should return the formatted response, to be sent by REST API to the user.

formatDataFn is an optional function to custom format non-error GraphQL responses (data). It receives a response argument which is the original response from GraphQL.

If not provided, default behavior is to strip the encapsulating 'data:' property and operation name, and omit the 'errors' array from successful responses.

expressRouter is an express.Router() instance to attach new routes to (if not provided, a new Express instance will be returned).


The options object:

For any fields not specified in the options object, or if options is not provided to init(), values from the defaults.json file will be used.

These are all optional settings that can be defined in options:

const gql2restOptions  = {
	apiPrefix: '/api/v2', //sets the API base path url
	manifestFile: './api-v2-manifest.json', //pathname of manifest file
	gqlGeneratorOutputFolder: './gqls', //.gql files folder (generated by generateGqlQueryFiles())
	middlewaresFile:  './middlewares.js', //optional middlewares module for modifying requests
	filterFieldName: 'fields', //global query parameter name for filtering (default is 'fields')
	graphqlErrorCodeObjPath:  'errors[0].extensions.code', //property name for GraphQL error code for error mapping
	logger: myCustomLogger //optional Winston-based logger function
};

const expressRouter = GraphQL2REST.init(schema, execute, gql2restOptions);

Use path.resolve(__dirname, <PATH>) for relative paths.

All fields in options are optional, but init() will not be able to run without a valid manifest file and gqlGeneratorOutputFolder previously populated by generateGqlQueryFiles().


Learn more about:


[Back to the tutorial]