diff --git a/docs/apollo-server/building-graphql-api-with-apollo-server.md b/docs/apollo-server/building-graphql-api-with-apollo-server.md index 1dd1350..ad3f6ef 100644 --- a/docs/apollo-server/building-graphql-api-with-apollo-server.md +++ b/docs/apollo-server/building-graphql-api-with-apollo-server.md @@ -2,76 +2,128 @@ ## Introduction -GraphQL has taken the world of APIs by storm. One of the most popular implementations of GraphQL on Node.js is Apollo Server. In this blog, we'll go over the basics of building a GraphQL API with Apollo Server. +GraphQL is a query language and runtime for APIs that was developed by Facebook. It allows clients to request only the data that they need from an API, which can lead to faster and more efficient data fetching. Apollo is a popular open-source implementation of GraphQL for Node.js and is commonly used for building APIs. -## What is Apollo in Node.js +In this blog post, we will be discussing the basics of building a GraphQL API with Apollo Server, including what Apollo is and how to work with it. -Apollo Server is a library that helps you build a GraphQL API on Node.js. It's built on top of the graphql-js library, which is a popular implementation of GraphQL on JavaScript. +## What is Apollo + +Apollo is a set of libraries and tools that can be used to build GraphQL APIs. It includes Apollo Server, which is a production-ready GraphQL server that can be used with any JavaScript HTTP server framework. Apollo also provides client libraries that make it easy to consume GraphQL APIs from web and mobile apps. ## Working with Apollo -### Setting up Apollo +### Setting up Apollo Server -To get started with Apollo Server, first, install the necessary packages. Run the following command to install the dependencies: +To get started with Apollo Server, we need to install the `apollo-server` npm package. This can be done by running the following command in your terminal: -```bash -npm install apollo-server graphql ``` - -Once you have the packages installed, you can create an Apollo Server by importing the `ApolloServer` class from the `apollo-server` package. - -```javascript -const { ApolloServer } = require('apollo-server'); +npm install apollo-server ``` -### Defining a Schema - -The next step is to define a schema for your API. A schema is essentially a contract between the server and the client that specifies what types of data the server can provide. You can define a schema using the `typeDefs` and `resolvers` properties of the `ApolloServer` class. +Once installed, we can create a new instance of Apollo Server by passing in a configuration object. Here's an example: ```javascript -const typeDefs = ` +const { ApolloServer, gql } = require('apollo-server'); + +// Define our GraphQL schema using the gql tag +const typeDefs = gql` type Query { hello: String } `; +// Define a resolver for our query const resolvers = { Query: { - hello: () => 'Hello World!' - } + hello: () => 'Hello world!', + }, }; +// Create a new instance of ApolloServer const server = new ApolloServer({ typeDefs, resolvers }); -``` - -In this example, we're defining a simple schema that exposes a single query called `hello` that returns the string `Hello World!`. - -### Running the Server -Once you have defined your schema, you can start the server by calling the `listen` method on the `ApolloServer` instance. - -```javascript +// Start the server server.listen().then(({ url }) => { - console.log(`🚀 Server ready at ${url}`); + console.log(`Server ready at ${url}`); }); ``` -This will start the Apollo Server and log the URL where it's running to the console. +In this example, we're defining a simple GraphQL schema that includes a single query called `hello` that returns a string. We've also defined a resolver for the `hello` query that returns the string `'Hello world!'`. Finally, we create a new instance of ApolloServer and start it listening on a port. -### Using GraphQL Studio +### Using GraphQL Playground -Apollo Server comes with a built-in GraphQL IDE called GraphQL Studio. You can access it by visiting the URL where your Apollo Server is running and appending `/graphql` to the end of it. +When we start Apollo Server, it automatically launches a GraphQL playground, which is a web-based IDE that can be used to interact with our API. The playground can be accessed by navigating to `http://localhost:4000` in a web browser (assuming we're running our server on port 4000). -![GraphQL Studio](https://i.imgur.com/3wVhVIH.png) +Using the playground, we can explore our API and execute queries. For example, we could execute the following query: -### Introspection +```graphql +query { + hello +} +``` -One of the powerful features of GraphQL is introspection. This allows you to query the API schema at runtime to see what queries, types, fields, and directives it supports. To enable introspection, set the `introspection` property to `true` when creating your `ApolloServer` instance. +This should return the following response: -```javascript -const server = new ApolloServer({ typeDefs, resolvers, introspection: true }); +```json +{ + "data": { + "hello": "Hello world!" + } +} +``` + +### Introspection + +One of the key benefits of using GraphQL is its introspection capabilities. Introspection refers to the ability to query which resources are available in the current API schema. Using introspection, we can see the queries, types, fields and directives that our API supports. + +Apollo provides a built-in `introspection` query that can be used to retrieve the current schema of our API. We can execute this query in GraphQL Playground by clicking the "Schema" tab and then clicking the "Introspection" button. + +Here's an example of what the `introspection` query response might look like: + +```json +{ + "__schema": { + "queryType": { + "name": "Query" + }, + "types": [ + { + "kind": "OBJECT", + "name": "Query", + "fields": [ + { + "name": "hello", + "args": [], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ] + }, + { + "kind": "SCALAR", + "name": "String", + "description": "The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text." + } + ] + } +} ``` +This response tells us that our API has a single query called `hello`, which returns a string. We can use this information to build more complex queries and to better understand the capabilities of our API. + ## Conclusion -Apollo Server makes it easy to build a GraphQL API on Node.js. With built-in GraphQL Studio and introspection support, it's a great choice for building APIs of any size. \ No newline at end of file +In this blog post, we've covered the basics of building a GraphQL API with Apollo Server. We've discussed what Apollo is, how to set up a basic server with Apollo, and how to use GraphQL Playground and introspection to explore our API. + +GraphQL and Apollo provide a powerful way to build APIs that are flexible, efficient, and easy to consume. By using these technologies, we can create APIs that meet the needs of our clients and provide a great developer experience. + +## Additional Resources + +- [Apollo Server Documentation](https://www.apollographql.com/docs/apollo-server/) +- [GraphQL Documentation](https://graphql.org/learn/) +- [GraphQL Playground Documentation](https://github.com/graphql/graphql-playground) \ No newline at end of file diff --git a/docs/graphql/big-picture.md b/docs/graphql/big-picture.md new file mode 100644 index 0000000..ec8f93a --- /dev/null +++ b/docs/graphql/big-picture.md @@ -0,0 +1,129 @@ +# GraphQL Big-Picture: A Beginner's Guide + +## Introduction + +GraphQL is a powerful API query language and runtime that was developed by Facebook in 2012. It is a specification that is language agnostic and provides a more efficient, powerful and flexible alternative to RESTful APIs. In this article, we will take a look at the key points of GraphQL and its core concepts. + +## What is GraphQL? + +GraphQL is a query language and runtime that moves the focus of development to client applications. With GraphQL, the client defines the structure of the data that it needs, and the server returns exactly that. This helps to eliminate the under-fetching, over-fetching, and unnecessary network round trips that are common with traditional RESTful APIs. + +GraphQL doesn't rely on the HTTP spec for caching and depends on development frameworks to perform the heavy lifting. This makes GraphQL more flexible and efficient between client and server applications. + +## GraphQL Core Concepts + +### Built-in Scalar Types + +GraphQL has built-in scalar types, including `Int`, `Float`, `String`, `Boolean`, `ID`, and `Enums`. + +### Queries + +Each schema contains at minimum a `Query` type. Queries are used to fetch data from the server. With GraphQL, all fields in a query run in parallel, and only the fields requested by the client are returned. + +### Queries Fields + +Fields are used to specify the data that the client wants to retrieve from the server. + +```graphql +query { + user { + firstName + lastName + age + } +} +``` + +### Queries Arguments + +Arguments are used to pass data to the server. Each field and nested object can get its own set of arguments. + +```graphql +query { + user(id: "123") { + firstName + lastName + age + } +} +``` + +### Queries Aliases + +Aliases are used to rename the result of a field with a given alias. + +```graphql +query { + firstName: user(id: "123") { + firstName + } + lastName: user(id: "123") { + lastName + } +} +``` + +### Queries Fragments + +Fragments are reusable units in GraphQL, like functions in other programming languages. + +```graphql +fragment UserInfo on User { + firstName + lastName + age +} + +query { + user(id: "123") { + ...UserInfo + } +} +``` + +### Queries Variables + +Variables are used to make GraphQL queries dynamic. + +```graphql +query($id: ID!) { + user(id: $id) { + firstName + lastName + age + } +} +``` + +### Mutations + +Mutations are used to create, update, and delete data in the server. Mutations always run in sequence. + +```graphql +mutation { + createUser( + input: { + firstName: "John" + lastName: "Doe" + age: 25 + } + ) { + id + firstName + lastName + age + } +} +``` + +## Why GraphQL? + +GraphQL provides a way to declaratively fetch data, allowing for a more efficient and powerful way to retrieve data from the server. With GraphQL, the schema contract between the frontend and the backend is stronger, providing a more solid foundation for development. GraphQL provides a superior developer experience, and it is a cost-effective solution since it leads to quicker development and self-documentation. + +## GraphQL Tools + +GraphQL Voyager is an interactive tool that displays relations between graphs. GraphQL Faker generates fake data for testing, and GraphQL Visual Editor converts visual blocks into code. + +## Conclusion + +GraphQL is a powerful query language and runtime that is more efficient, powerful and flexible than traditional RESTful APIs. Its built-in scalar types, queries, mutations, and other features provide a superior developer experience, making it an ideal choice for modern web applications. \ No newline at end of file