Apollo Server Core provides functions and utilities for processing HTTP requests and integrating with various Node.js HTTP frameworks and serverless environments.
Core function for processing HTTP requests containing GraphQL queries and converting them to GraphQL operations.
/**
* Process HTTP requests containing GraphQL queries
* @param request - HTTP request with GraphQL query data
* @returns Promise resolving to HTTP response with GraphQL results
*/
function runHttpQuery(request: HttpQueryRequest): Promise<HttpQueryResponse>;
interface HttpQueryRequest {
/** HTTP method (GET, POST, etc.) */
method: string;
/** Query data from POST body or GET query string */
query: Record<string, any> | Array<Record<string, any>>;
/** GraphQL execution options or function that returns options */
options:
| GraphQLOptions
| ((...args: Array<any>) => ValueOrPromise<GraphQLOptions>);
/** HTTP request information */
request: Pick<Request, 'url' | 'method' | 'headers'>;
}
interface HttpQueryResponse {
/** Stringified GraphQL response body */
graphqlResponse: string;
/** HTTP response configuration */
responseInit: ApolloServerHttpResponse;
}
interface ApolloServerHttpResponse {
/** HTTP response headers */
headers?: Record<string, string>;
/** HTTP status code */
status?: number;
}Usage Example:
import { runHttpQuery } from "apollo-server-core";
// Process an HTTP request with GraphQL query
const response = await runHttpQuery({
method: 'POST',
query: {
query: '{ hello }',
variables: {},
operationName: null,
},
options: {
schema: mySchema,
context: { user: req.user },
},
request: {
url: req.url,
method: req.method,
headers: req.headers,
},
});
// Send response
res.status(response.responseInit.status || 200);
res.set(response.responseInit.headers);
res.send(response.graphqlResponse);Error types and utilities for HTTP query processing.
/**
* Error thrown during HTTP query processing
*/
class HttpQueryError extends Error {
/** HTTP status code for the error */
statusCode: number;
/** Error headers */
headers?: Record<string, string>;
/** Whether error is safe to expose to clients */
isGraphQLError: boolean;
constructor(
statusCode: number,
message: string,
isGraphQLError: boolean = false,
headers?: Record<string, string>
);
}
/**
* Type guard to check if error is HttpQueryError
* @param error - Error to check
* @returns true if error is HttpQueryError
*/
function isHttpQueryError(error: any): error is HttpQueryError;Error Handling Example:
import { runHttpQuery, isHttpQueryError } from "apollo-server-core";
try {
const response = await runHttpQuery(request);
res.status(200).send(response.graphqlResponse);
} catch (error) {
if (isHttpQueryError(error)) {
res.status(error.statusCode);
if (error.headers) {
res.set(error.headers);
}
res.send(error.message);
} else {
res.status(500).send('Internal Server Error');
}
}Utility for converting Node.js HTTP requests to Apollo Server request format.
/**
* Convert Node.js HTTP request to Apollo Server request format
* @param req - Node.js HTTP request
* @param body - Optional parsed request body
* @returns Apollo Server request object
*/
function convertNodeHttpToRequest(
req: http.IncomingMessage,
body?: any
): Pick<Request, 'url' | 'method' | 'headers' | 'body'>;Node.js Integration Example:
import http from 'http';
import { convertNodeHttpToRequest, runHttpQuery } from "apollo-server-core";
const server = http.createServer(async (req, res) => {
if (req.url === '/graphql') {
try {
// Parse request body (simplified)
let body = '';
req.on('data', chunk => body += chunk);
req.on('end', async () => {
const parsedBody = JSON.parse(body);
const apolloRequest = convertNodeHttpToRequest(req, parsedBody);
const response = await runHttpQuery({
method: req.method || 'GET',
query: parsedBody,
options: {
schema: mySchema,
context: { req, res },
},
request: apolloRequest,
});
res.writeHead(
response.responseInit.status || 200,
response.responseInit.headers
);
res.end(response.graphqlResponse);
});
} catch (error) {
res.writeHead(500);
res.end('Internal Server Error');
}
} else {
res.writeHead(404);
res.end('Not Found');
}
});Internal request pipeline types for advanced integrations.
interface GraphQLRequest {
/** GraphQL query string */
query: string;
/** Operation name (for multiple operations in query) */
operationName?: string;
/** Variable values for the query */
variables?: VariableValues;
/** Extensions to the request */
extensions?: Record<string, any>;
/** HTTP-specific request information */
http?: Pick<Request, 'url' | 'method' | 'headers' | 'body'>;
}
interface GraphQLResponse {
/** Query result data */
data?: Record<string, any> | null;
/** Execution errors */
errors?: readonly GraphQLFormattedError[];
/** Extensions to the response */
extensions?: Record<string, any>;
/** HTTP-specific response information */
http?: Pick<Response, 'body' | 'headers' | 'status'>;
}
type VariableValues = { readonly [variable: string]: unknown };Context objects used throughout the request processing pipeline.
interface GraphQLRequestContext<TContext = Record<string, any>> {
/** The incoming GraphQL request */
request: GraphQLRequest;
/** The GraphQL response (available after execution) */
response?: GraphQLResponse;
/** Logger instance */
logger: Logger;
/** GraphQL schema */
schema: GraphQLSchema;
/** Schema hash */
schemaHash: SchemaHash;
/** Context value for resolvers */
context: TContext;
/** Cache implementation */
cache: KeyValueCache;
/** Parsed GraphQL document */
document?: DocumentNode;
/** Selected operation from document */
operation?: OperationDefinitionNode;
/** Operation name */
operationName?: string;
/** Variable values */
variables?: VariableValues;
/** Query source (for persisted queries) */
source?: string;
/** Request metrics */
metrics: GraphQLRequestMetrics;
}
interface GraphQLRequestMetrics {
/** Time when request started processing */
startHrTime: [number, number];
/** Duration of query parsing */
queryPlanningPhase?: {
startOffset: number;
duration: number;
};
/** Duration of query validation */
validationPhase?: {
startOffset: number;
duration: number;
};
/** Duration of query execution */
executionPhase?: {
startOffset: number;
duration: number;
};
}Common patterns for integrating Apollo Server Core with different frameworks.
Express Integration Pattern:
import express from 'express';
import { ApolloServerBase } from 'apollo-server-core';
const app = express();
const server = new ApolloServerBase({ typeDefs, resolvers });
await server.start();
app.use('/graphql', express.json(), async (req, res) => {
const handler = server.createHandler();
return handler(req, res);
});Lambda Integration Pattern:
import { ApolloServerBase } from 'apollo-server-core';
const server = new ApolloServerBase({ typeDefs, resolvers });
await server.start();
export const handler = async (event, context) => {
const response = await server.executeOperation({
query: event.body.query,
variables: event.body.variables,
operationName: event.body.operationName,
}, {
event,
context,
});
return {
statusCode: 200,
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(response),
};
};