Introduction to GraphQL

Software developers constantly explore innovative methods to enhance client-server interactions as web and mobile applications evolve. One of the most significant advancements in this area in recent years is GraphQL, an open-source query language and runtime designed for API manipulation.

In this blog post, we will delve into what GraphQL is, explore its core concepts and terminology, and examine how it stacks up against the REST architectural style. Unlike SQL, which is used to interact directly with databases, GraphQL is not a database query language. Instead, it establishes a contract for communication between a client and an API server. The GraphQL specification serves as an open standard that outlines the rules and characteristics of the language and how to run GraphQL queries effectively.

What is GraphQL and how does it work?

GraphQL and REST are both approaches for enabling data exchange between systems, but they have distinct characteristics and use cases. REST, representing Representational State Transfer, is an architectural style that relies on multiple endpoints to share data. Each endpoint typically corresponds to a specific resource, and REST APIs adhere to principles such as being stateless, cacheable and having a uniform interface using URIs.

In contrast, GraphQL specifies a query language and runtime that operates over a single endpoint. It helps clients to request precisely the data they need, which can reduce the number of network requests compared to REST, where multiple endpoints might be required to gather all necessary information.

Regarding data fetching, REST APIs often return a fixed set of data, which may be either excessive or insufficient for the client's needs. GraphQL addresses this issue by letting clients specify their required data, preventing over and under-fetching.

Error handling differs between the two: REST APIs use HTTP status codes to indicate the success or failure of requests. GraphQL typically responds with a 200 HTTP status code and includes an errors field in the response payload if issues are encountered.

Versioning is another area where they diverge. REST commonly uses versioning in the URL, such as v1 or v2, to manage changes over time. GraphQL aims to avoid breaking changes and maintain backward compatibility, though it is possible to implement versioning in GraphQL if needed.

Caching is built into the REST architecture through HTTP conventions, which can efficiently manage resources across multiple endpoints. GraphQL, with its single endpoint structure, does not directly leverage HTTP caching mechanisms but can use client-side caching strategies such as Global Object Identification. While this overview highlights key differences and similarities, it's worth noting that GraphQL can also be employed as a gateway to aggregate data from multiple REST endpoints, allowing both technologies to be used together effectively.

PayPal APIs rely on REST, utilize OAuth 2.0 access tokens for authentication, and provide responses in JSON format with corresponding HTTP status codes. Learn more here. 

Benefits of GraphQL

The benefits of GraphQL make it a compelling choice for many use cases, particularly where efficiency and flexibility are key. One of the primary GraphQL advantages is its ability to fetch multiple pieces of data in a single request, significantly reducing network overhead and improving performance. Another GraphQL benefit is optimizing data transfer, as it sends only the necessary fields, reducing payload size and improving response times.

GraphQL advantages extend to the developer experience with strong typing through its schema, which improves code auto-completion, error detection, and overall development efficiency. Its intuitive query language simplifies data fetching compared to complex REST endpoints. Moreover, GraphQL’ s schema can evolve without disrupting existing clients, making API maintenance more manageable.

Clients have full control over their data requests, as GraphQL allows responses to be tailored to specific needs. It uses a single endpoint for all data operations, simplifying integration and management. Additionally, it efficiently handles complex data relationships and nested structures, making it ideal for intricate scenarios such as ecommerce and payment systems.

GraphQL supports real-time updates through subscriptions, enabling features such as live order tracking or inventory changes, which enhances interactivity and user engagement.

Potential disadvantages of GraphQL

One unique challenge is the increased complexity in caching, as GraphQL responses are dynamic and less predictable than REST's well-defined endpoints. Another unique issue is the possibility of over-fetching or under-fetching data, requiring careful query design to avoid inefficient queries. Common disadvantages shared with other alternatives, like REST, include security concerns, such as exposure to denial-of-service (DoS) attacks through costly or complex queries. Learning and adopting GraphQL can also involve a steep learning curve, like other modern API technologies.

How does PayPal use GraphQL?

PayPal Braintree, PayPal’s global payment processing solution that delivers end-to-end checkout experiences for businesses, exposes GraphQL as the API that merchants can integrate with. The GraphQL API exposes all the functionality required to integrate with Braintree. PayPal's Braintree platform utilizes GraphQL as its primary API for merchants to manage payment processing and access robust reporting and transaction features. Braintree leverages the GraphQL API to expose all the functionalities merchants need for seamless integration. One of the key reasons PayPal chose GraphQL for Braintree is its strongly typed schema, which simplifies the integration process by providing a clear structure and improving error detection. Additionally, the nested schema in GraphQL allows merchants to reduce the number of API calls, as it enables fetching related data in a single request, thus improving efficiency and reducing network overhead. This approach optimizes the overall experience for merchants managing complex payment systems. 

How to use GraphQL

PayPal Braintree provides comprehensive resources and tools to help merchants integrate with its GraphQL API seamlessly. Merchants can also explore Payments API concepts, understanding how Braintree models payment processes. Practical guidance on making API calls, including building and authenticating requests, is also available. To get started, merchants can easily create a sandbox account to obtain API keys and begin experimenting with GraphQL Explorer for testing and refining their integration.

Learn more here: https://graphql.braintreepayments.com/

As the PayPal Braintree GraphQL requests are over HTTP, the below examples use curl, and you can start testing the API from the command line. 

Example: 

First Request:

The simplest request is ping. It is mainly useful to ensure you understand how to generate well-formed requests. Here's the GraphQL query:

query {   ping }

To send that to our API, it must be wrapped in a JSON object with a query key:

{ "query": "query { ping }" }

And here's how it all fits together, using curl: 

curl  -H 'Authorization: Basic BASE64_ENCODED(PUBLIC_KEY:PRIVATE_KEY)'  -H 'Braintree-Version: 2019-01-01'  -H 'Content-Type: application/json'  -X POST https://payments.sandbox.braintree-api.com/graphql  -d '{"query": "query { ping }"}'

The response looks like this: 

{   "data": {     "ping": "pong"   },  "extensions": {     "requestId": "a-uuid-for-the-request"   } }

To learn more about making API calls with GraphQL, visit the API Basics page. 

GraphQL is also ideal for applications that require data from multiple sources in a single request, such as dashboards, ecommerce platforms, or content-heavy apps. Additionally, real-time updates through GraphQL subscriptions make it suitable for dynamic environments such as live tracking or collaborative tools. GraphQL is suitable when API evolution needs to be smooth without breaking changes for clients. Any application that requires flexibility in data fetching is essential, and GraphQL could be a good use case for It. It excels when clients need to request specific data fields, reducing over-fetching and under-fetching issues, especially in scenarios with complex or nested data structures. 

Getting started with GraphQL

Integrating GraphQL with PayPal is a straightforward and easy process. The guide covers an overview of the basic steps to help you get started, from setting up your development environment to making your first API request.

If you: 

• Have not used GraphQL before: About GraphQL
• Want an ideas-first look at our API: API Concepts
• Want to jump in with concrete examples: Making API Calls
• Learn by doing and want to try it out first: API Explorer
• Need a changelog for the full API: GitHub Schema Report

Learn more about getting started with GraphQL for PayPal Braintree integration guides here: https://graphql.braintreepayments.com/guides/