@gramps/gramps-express

GrAMPS GraphQL Middleware for Apollo Express Server

An easier way to manage the data sources powering your GraphQL server.

GrAMPS (short for GraphQL Apollo Microservice Pattern Server) is middleware designed for apollo-server-express that allows independent data sources — a schema, resolvers, and data access model — to be composed into a single GraphQL schema, while keeping the code within each data source isolated, independently testable, and completely decoupled from the rest of your application.

Developer Quickstart

See the 5-minute quickstart in our documentation.

Why Does GrAMPS Exist?

GrAMPS is an attempt to create a standard for organizing GraphQL data source repositories, which allows for multiple data sources to be composed together in a plugin-like architecture.

The architecture of GrAMPS data sources was inspired by @helfer, who suggested models and connectors as abstractions when designing GraphQL servers. GrAMPS expands on the original concept and provides a standard that makes separate codebases interoperable.

The ability to combine independently managed data sources into a single GraphQL server is a core requirement for IBM Cloud’s microservice architecture. We have dozens of teams who expose data, so a single codebase with all GraphQL data sources inside was not an option; we needed a way to give each team control of their data while still maintaining the ability to simplify our data layer.

GrAMPS solves this problem by allowing each data source to be an independent repository/package that can be composed together into a single GraphQL server.

What GrAMPS Can Do

• Combine distinct schemas into a single GraphQL schema
• Allow local development with optional local overrides of data sources
• Improve error reporting with optional error handling

How GrAMPS Works

1. Import each GrAMPS data source as an npm package
2. Check for local data sources specified in GQL_DATA_SOURCES or in the --data-source-dir argument to the CLI command gramps
3. Merge all GrAMPS data sources into a single GraphQL schema
4. Attach the combined schema and context to the Express request
5. Use the GrAMPS schema and context in graphqlExpress to start the server

Roadmap

• Write a data source tutorial (#21, WIP at #22)
• Write a developer quickstart (#23)
• Add API docs (#24)
• Write docs about how error handling works (#25)
• Add a Redis add-on (#26)
• Add simpler cache key override (#27)
• Define a pattern for direct database access (#28)
• Add all-contributors (#29)
• Add integration test examples/docs with Cypress (#30)

Credits

GrAMPS was born at IBM Cloud to solve the problem of maintaining a single GraphQL endpoint in a µ-service architecture where data sources are owned by dozens of teams.

We’re releasing it under the MIT license because we ❤️ the developer community.