PetstoreAPI GraphQL Protocol Guide

Modern Petstore API provides GraphQL support for flexible, efficient data fetching where clients request exactly what they need in a single query. Our GraphQL endpoint at https://api.petstoreapi.com/v1/graphql enables complex nested queries, multiple resources in single requests, and precise field selection to reduce payload size for mobile applications.

Overview

Protocol: GraphQL over HTTPS

Endpoint: https://api.petstoreapi.com/v1/graphql

Query Language: GraphQL

When to Use GraphQL:

✅ Complex, nested data requirements

✅ Mobile applications (reduce payload size)

✅ Multiple resources in single request

✅ Flexible, self-documenting API

✅ Different clients need different fields

When NOT to Use GraphQL:

❌ Simple CRUD operations (use REST instead)

❌ File uploads (use REST instead)

❌ Need HTTP caching (REST has better caching)

How GraphQL Works

Client                          GraphQL Server
    │                                  │
    ├──── Query ─────────────────────>│
    │  { pets { id name species } }   │
    │                                  │
    │                         ┌────────┴────────┐
    │                         │ Parse Query    │
    │                         │ Validate       │
    │                         │ Execute        │
    │                         └────────┬────────┘
    │                                  │
    │<──── JSON Response ─────────────┤
    │  { "data": { "pets": [...] } }  │

Key Characteristics:

Request exactly the data you need

Single request for multiple resources

Strongly typed schema

Introspection (self-documenting)

No overfetching or underfetching

Basic Queries

List Pets

Response:

{
  "data": {
    "pets": [
      {
        "id": "019b4132-70aa-764f-b315-e2803d882a24",
        "name": "Buddy",
        "species": "DOG",
        "breed": "Golden Retriever",
        "ageMonths": 24,
        "status": "AVAILABLE"
      }
    ]
  }
}

Get Single Pet

Variables:

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24"
}

Filter Pets

Pagination

Mutations

Create Pet

Update Pet

Delete Pet

Nested Queries

Pet with Owner

Order with Items

Authentication

Include JWT token in Authorization header:

Code Examples

JavaScript (fetch)

JavaScript (Apollo Client)

Python (gql)

Advanced Features

Fragments

Reuse common fields:

Directives

Conditionally include fields:

Aliases

Rename fields in response:

Multiple Queries

Introspection

Query the schema:

Get type details:

Best Practices

1. Use Specific Fields

2. Batch Queries

3. Use Fragments for Reuse

Error Handling

GraphQL errors are returned in the response:

{
  "data": {
    "pet": null
  },
  "errors": [
    {
      "message": "Pet not found",
      "path": ["pet"],
      "extensions": {
        "code": "PET_NOT_FOUND"
      }
    }
  ]
}

Handle errors in code:

Comparison with REST

Feature	GraphQL	REST
Data Fetching	Exact fields	Fixed responses
Requests	Single for multiple resources	Multiple endpoints
Overfetching	No	Yes (often)
Underfetching	No	Yes (n+1 problem)
Caching	Complex	HTTP caching built-in
Schema	Strongly typed	Varies
Documentation	Self-documenting	Separate (OpenAPI)

Interactive Documentation

GraphQL Playground: https://api.petstoreapi.com/v1/graphql

Protocol Overview: All Protocols

REST API Guide: REST Protocol

GraphQL Specification

Apollo Documentation

Quick Start Guide

Overview#

How GraphQL Works#

Basic Queries#

List Pets#

Get Single Pet#

Filter Pets#

Pagination#

Mutations#

Create Pet#

Update Pet#

Delete Pet#

Nested Queries#

Pet with Owner#

Order with Items#

Authentication#

Code Examples#

JavaScript (fetch)#

JavaScript (Apollo Client)#

Python (gql)#

Advanced Features#

Fragments#

Directives#

Aliases#

Multiple Queries#

Introspection#

Best Practices#

1. Use Specific Fields#

2. Batch Queries#

3. Use Fragments for Reuse#

Error Handling#

Comparison with REST#

Interactive Documentation#

Related Resources#