Making Your First Request

Now that you have authentication set up, let's make your first API call to the Trading Card API. This guide will walk you through fetching card data and understanding the response structure.

🎯 What You'll Learn

• How to structure API requests
• Understanding JSON:API response format
• Working with pagination
• Basic filtering and sorting
• Error handling

🚀 Quick Test

Let's start with a simple request to fetch cards:

curl -X GET "https://api.tradingcardapi.com/cards?page[limit]=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json"

Replace YOUR_ACCESS_TOKEN

Make sure to replace YOUR_ACCESS_TOKEN with the actual token you received in the authentication step.

📊 Understanding the Response

Basic Response Structure

All API responses follow the JSON:API specification:

{
  "data": [
    {
      "type": "cards",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "attributes": {
        "name": "1989 Topps Ken Griffey Jr. #336",
        "number": "336",
        "year": 1989,
        "description": "Ken Griffey Jr. rookie card",
        "serial_number": null,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      "relationships": {
        "set": {
          "data": {
            "type": "sets",
            "id": "fedcba98-7654-3210-fedc-ba9876543210"
          }
        },
        "oncard": {
          "data": [
            {
              "type": "players",
              "id": "abcdef01-2345-6789-abcd-ef0123456789"
            }
          ]
        },
        "attributes": {
          "data": []
        }
      },
      "links": {
        "self": "https://api.tradingcardapi.com/cards/01234567-89ab-cdef-0123-456789abcdef"
      }
    }
  ],
  "meta": {
    "total": 1247831,
    "per_page": 5,
    "current_page": 1,
    "last_page": 249567,
    "from": 1,
    "to": 5
  },
  "links": {
    "first": "https://api.tradingcardapi.com/cards?page[limit]=5&page[number]=1",
    "last": "https://api.tradingcardapi.com/cards?page[limit]=5&page[number]=249567",
    "next": "https://api.tradingcardapi.com/cards?page[limit]=5&page[number]=2"
  }
}

Response Components

Component	Description
data	Array of resource objects (cards in this case)
meta	Metadata about the response (pagination info, totals)
links	Navigation links for pagination
included	Related resources when using includes

🔍 Exploring Card Data

Card Attributes

Each card has these primary attributes:

{
  "name": "1989 Topps Ken Griffey Jr. #336",
  "number": "336",
  "year": 1989,
  "description": "Ken Griffey Jr. rookie card",
  "serial_number": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Attribute	Type	Description
name	string	Auto-generated card name
number	string	Card number within the set
year	integer	Year the card was released
description	string	Additional card information
serial_number	string/null	Serial number for limited cards

Card Relationships

Cards relate to other resources:

• set: The card set this card belongs to
• oncard: Entities that appear on the card (players, teams, etc.)
• attributes: Special attributes (autographs, variations, etc.)

🔗 Including Related Data

Use the include parameter to fetch related data in one request:

curl -X GET "https://api.tradingcardapi.com/cards?include=set,oncard&page[limit]=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

This returns the card data plus related sets and oncard entities in the included section:

{
  "data": [...],
  "included": [
    {
      "type": "sets",
      "id": "fedcba98-7654-3210-fedc-ba9876543210",
      "attributes": {
        "name": "1989 Topps Baseball",
        "year": 1989,
        "total_cards": 792,
        "description": "Complete baseball set from Topps"
      }
    },
    {
      "type": "players",
      "id": "abcdef01-2345-6789-abcd-ef0123456789",
      "attributes": {
        "name": "Ken Griffey Jr.",
        "position": "Outfield",
        "birth_date": "1969-11-21"
      }
    }
  ]
}

🎛️ Filtering and Sorting

Basic Filtering

Filter cards by specific criteria:

# Cards from 1989
curl -X GET "https://api.tradingcardapi.com/cards?filter[year]=1989" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

# Cards with specific number
curl -X GET "https://api.tradingcardapi.com/cards?filter[number]=336" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

# Cards containing text in name
curl -X GET "https://api.tradingcardapi.com/cards?filter[name]=*Griffey*" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

Sorting

Sort results by any attribute:

# Sort by year (descending)
curl -X GET "https://api.tradingcardapi.com/cards?sort=-year" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

# Sort by name (ascending)
curl -X GET "https://api.tradingcardapi.com/cards?sort=name" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

# Multiple sort fields
curl -X GET "https://api.tradingcardapi.com/cards?sort=year,-number" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

📄 Pagination

Basic Pagination

Control how many results you get:

# Get 25 cards per page
curl -X GET "https://api.tradingcardapi.com/cards?page[limit]=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

# Get page 3 with 10 cards per page
curl -X GET "https://api.tradingcardapi.com/cards?page[limit]=10&page[number]=3" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/vnd.api+json"

Using Pagination Links

The response includes navigation links:

{
  "links": {
    "first": "https://api.tradingcardapi.com/cards?page[limit]=10&page[number]=1",
    "prev": "https://api.tradingcardapi.com/cards?page[limit]=10&page[number]=2", 
    "next": "https://api.tradingcardapi.com/cards?page[limit]=10&page[number]=4",
    "last": "https://api.tradingcardapi.com/cards?page[limit]=10&page[number]=124784"
  }
}

💻 Code Examples

PHP

<?php

// Assuming you have the TradingCardAPI class from the authentication guide

$api = new TradingCardAPI('your_client_id', 'your_client_secret');
$api->authenticate();

// Get recent cards
$recentCards = $api->getCards([
    'sort' => '-created_at',
    'page[limit]' => 10
]);

// Get cards from a specific year with set information
$cards1989 = $api->getCards([
    'filter[year]' => 1989,
    'include' => 'set',
    'page[limit]' => 25
]);

// Search for Ken Griffey Jr. cards
$griffeyCards = $api->getCards([
    'filter[name]' => '*Griffey*',
    'include' => 'set,oncard',
    'sort' => 'year'
]);

foreach ($griffeyCards['data'] as $card) {
    echo "Card: " . $card['attributes']['name'] . "\n";
    echo "Year: " . $card['attributes']['year'] . "\n";
    echo "Number: " . $card['attributes']['number'] . "\n\n";
}

JavaScript

// Assuming you have the TradingCardAPI class from the authentication guide

const api = new TradingCardAPI('your_client_id', 'your_client_secret');
await api.authenticate();

// Get recent cards
const recentCards = await api.getCards({
  'sort': '-created_at',
  'page[limit]': 10
});

// Get cards from a specific year with set information
const cards1989 = await api.getCards({
  'filter[year]': 1989,
  'include': 'set',
  'page[limit]': 25
});

// Search for Ken Griffey Jr. cards
const griffeyCards = await api.getCards({
  'filter[name]': '*Griffey*',
  'include': 'set,oncard',
  'sort': 'year'
});

griffeyCards.data.forEach(card => {
  console.log(`Card: ${card.attributes.name}`);
  console.log(`Year: ${card.attributes.year}`);
  console.log(`Number: ${card.attributes.number}\n`);
});

Python

# Assuming you have the TradingCardAPI class from the authentication guide

api = TradingCardAPI('your_client_id', 'your_client_secret')
api.authenticate()

# Get recent cards
recent_cards = api.get_cards({
    'sort': '-created_at',
    'page[limit]': 10
})

# Get cards from a specific year with set information
cards_1989 = api.get_cards({
    'filter[year]': 1989,
    'include': 'set',
    'page[limit]': 25
})

# Search for Ken Griffey Jr. cards
griffey_cards = api.get_cards({
    'filter[name]': '*Griffey*',
    'include': 'set,oncard',
    'sort': 'year'
})

for card in griffey_cards['data']:
    print(f"Card: {card['attributes']['name']}")
    print(f"Year: {card['attributes']['year']}")
    print(f"Number: {card['attributes']['number']}\n")

❌ Error Handling

Common Error Responses

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "The filter parameter 'invalid_field' is not supported",
      "source": {
        "parameter": "filter[invalid_field]"
      }
    }
  ]
}

Handling Errors in Code

try {
  const cards = await api.getCards({ 'filter[invalid]': 'test' });
} catch (error) {
  if (error.response && error.response.data.errors) {
    error.response.data.errors.forEach(err => {
      console.error(`Error ${err.status}: ${err.detail}`);
    });
  }
}

🧪 Testing Your Requests

Using the API Explorer

Visit our interactive API explorer to test requests without writing code:

1. Navigate to the Cards endpoint
2. Add parameters like filtering and sorting
3. Execute the request and see the response
4. Copy the generated code to your application

Common Test Scenarios

# 1. Basic connectivity test
curl -X GET "https://api.tradingcardapi.com/cards?page[limit]=1"

# 2. Test with authentication
curl -X GET "https://api.tradingcardapi.com/cards?page[limit]=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. Test filtering
curl -X GET "https://api.tradingcardapi.com/cards?filter[year]=2023&page[limit]=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 4. Test includes
curl -X GET "https://api.tradingcardapi.com/cards?include=set&page[limit]=3" \
  -H "Authorization: Bearer YOUR_TOKEN"

🎯 Next Steps

Great! You've made your first API request. Now explore:

1. Common patterns → - Learn typical API usage patterns
2. JSON:API concepts → - Deep dive into the specification
3. Build a card tracker → - Complete tutorial
4. Explore all endpoints → - Full API reference

💡 Pro Tips

• Start small: Begin with simple requests and gradually add complexity
• Use includes: Fetch related data in single requests to improve performance
• Cache responses: Store frequently accessed data to reduce API calls
• Monitor rate limits: Keep track of your usage to avoid throttling

Ready to build something amazing? Let's explore common API patterns!