Overview of GraphQL

If you’re new to GraphQL, Apollo has blog post with the list of resources for beginners. Another good starting point is the official GraphQL documentation.

GraphQL is a query language for APIs and a runtime for executing those queries by using a type system defined with a schema. GraphQL allows clients to request exactly the data they need, and nothing more, making it efficient and flexible.

GraphQL structures requests in a language that’s similar to JSON, but it’s not JSON. GraphQL requests don’t use quotes for field names and fields and values are not separated by colons.

Here’s an example GraphQL request:

query {
  part(id: "itm_0113ZW53XRJ3NRMHHE07R2NSVN") {
    id
    manufacturerPn
    manufacturer {
      name
    }
  }
}

GraphQL responses are in JSON format. Here’s an example response:

{
  "data": {
    "part": {
      "id": "itm_0113ZW53XRJ3NRMHHE07R2NSVN",
      "manufacturerPn": "XC3S400-4PQ208C",
      "manufacturer": {
        "name": "Xilinx"
      }
    }
  }
}

Differences from REST

Unlike REST, where each endpoint returns a fixed data structure, GraphQL uses a single endpoint to query multiple resources. In REST, the structure of the response is determined by the server, leading to over-fetching or under-fetching of data. With GraphQL, the client specifies the shape and size of the required data, ensuring that only the necessary information is retrieved.

Benefits of GraphQL over REST

1. Self-Documenting: The strongly typed schema of GraphQL serves as a built-in documentation, making it easier for clients to understand the available data and how to query it. This enhances the developer experience and speeds up the integration process.
2. Precise Data Fetching: Clients can request exactly the data they need, reducing the amount of data transferred over the network. This minimizes bandwidth usage and improves the efficiency of data handling.
3. Connected Data Fetching: GraphQL excels at retrieving interconnected or related data in one query, thanks to its ability to follow and resolve relationships within the schema. This ensures that complex, relational datasets can be fetched efficiently, reducing the need for multiple round-trips to the server and simplifying data handling on the client side.
4. Batch Multiple Requests: GraphQL allows clients to retrieve data from multiple resources in a single query. This reduces the number of network requests and leads to faster data retrieval, improving performance and user experience.
5. Reduced Overfetching and Underfetching: By requesting only the needed data, clients avoid receiving extraneous information (overfetching) or needing multiple requests to gather all necessary data (underfetching), leading to more efficient data usage.
6. Single Endpoint Access: Clients interact with a single endpoint to fetch all necessary data, simplifying the API interaction and reducing the complexity of managing multiple REST endpoints.

Terminology

Here are the key GraphQL concepts:

1. Query: The primary way to fetch data from a GraphQL server. Queries specify exactly what data is needed, allowing for efficient data retrieval. Queries can be structured to nest related data requests.
2. Mutation: Used to modify data on the server, such as creating, updating, or deleting records. Mutations can also return data, allowing immediate visibility of the result of operations.
3. Schema: Defines the structure of the API, including the types of data and the relationships between them. The schema informs about what queries and mutations are available and what data can be accessed.
4. Type: Represents the shape of the data that can be queried or mutated. Key types include:
   • Scalar Types: Basic data types like Int, Float, String, Boolean, and ID.
   • Object Types: Custom types that group related fields, such as Part, PurchaseOrder, etc.
5. Input Object: A special type used to pass complex data structures as arguments to queries and mutations. Input objects allow grouping related fields into a single argument, making it easier to handle complex inputs. For example, an ContactInput object might include fields like firstName, lastName, and email.
6. Field: Represents a specific piece of data that can be queried on a type. Fields specify exactly what data is needed from an object type.
7. Arguments: Allow customization of queries and mutations by passing additional information. For example, arguments can be used to filter, sort, or paginate data.
8. Connection: A pattern used to model relationships between types, especially for handling pagination. A connection typically includes information about the total count of items, the edges in the current page, and pagination info like cursors.
9. Edge: Represents a single link in a connection. Each edge contains a node (the actual data item) and a cursor (a unique identifier used for pagination).
10. Node: The actual data item in a connection. Nodes are the core elements that edges link to within a connection.
11. Introspection: Allows querying the GraphQL API for details about its schema. This helps understand the available types, fields, and operations, facilitating easier integration and tool development.

These concepts are essential for effectively interacting with a GraphQL API, allowing for fetching, modifying, and subscribing to data efficiently and with precision.