-
Notifications
You must be signed in to change notification settings - Fork 2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
initial design document for apollo server (#19)
* initial design document for apollo server * update DESIGN.md to clarify some things
- Loading branch information
Showing
1 changed file
with
37 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,37 @@ | ||
# Apollo Server design goals | ||
|
||
The goal of this project is to build a GraphQL server for Node.js that is simple, flexible, and performant. It is a Node.js GraphQL server built for production use. | ||
|
||
Apollo Server consists of three parts: | ||
|
||
1. Core | ||
2. Integrations | ||
3. Extensions | ||
|
||
At the core of Apollo Server is a function called `runQuery`, which handles parsing, validating and executing queries. Its interface is generic in order to allow for integrations with different Node.js server frameworks. Extensions provide useful functionality that can be shared between different integrations. | ||
|
||
|
||
### Core | ||
|
||
The main goals of Apollo Server are (in order of priority): | ||
|
||
1. Simplicity: Apollo Server鈥檚 core API is very straight forward. It鈥檚 one function that does one thing really well (parsing, validating and executing GraphQL queries), and doesn鈥檛 do anything else. | ||
2. Flexibility: The core of Apollo Server should be transport-agnostic (e.g. it doesn鈥檛 deal with HTTP or Websockets directly. This is will be handled in the wrappers for Express, HAPI, etc.) | ||
3. Performance: Apollo server should be be tunable to make it fast in production. One example of this is that it should be able to take pre-stored queries to skip parsing and validation. It should also allow easy integration of profiling tools like Apollo Tracer that help with debugging and optimizing server performance. | ||
|
||
### Integrations | ||
|
||
Apollo Server should come with a set of integrations for different Node.js server frameworks: | ||
|
||
- Express | ||
- HAPI | ||
- Connect | ||
- Koa | ||
- ... | ||
|
||
Framework integrations take care of parsing requests, submitting them to Apollo Server鈥檚 core runQuery function, and sending the response back to the client. These integrations should accept requests over HTTP, websockets or other means, then invoke `runQuery` as appropriate, and return the result. They should be written in such a way that makes it easy to add features, such as batched queries, subscriptions etc. | ||
|
||
Framework integrations should hide all transport-specific (eg. setting headers) and framework-specific things (eg. registering a route) from the core functions. | ||
|
||
### Modules | ||
Things that are not part of runQuery鈥檚 tasks, but are GraphQL specific (such as providing a bundle for the GraphiQL UI, generating a schema, storing prepared queries, etc.) should be implemented in another core module of Apollo Server that lives alongside runQuery, or be imported from graphql-tools or other related packages. |