Quick Start Guide

Quick Start Guide

Get up and running with Firefly! This guide will walk you through making your first GraphQL query in minutes.

Prerequisites

• Access to music.amazon.com

Step 1: Access the GraphQL Console

1. Navigate to the GraphQL Console

2. Click Login with Amazon

3. Sign in with your Amazon account (same one you use for music.amazon.com)

4. Click Allow to grant permissions

Step 2: Your First Query

Start with a simple query to get your user information:

query GetUser {
  user {
    id
    name
    tier
  }
}

Try in GQL Console

1. Copy the query above into the center panel

2. Click the Play button (▶️) to execute

3. View the results in the right panel

You should see something like:

{
  "data": {
    "user": {
      "id": "A1234567890",
      "name": "Your Name",
      "tier": "UNLIMITED"
    }
  }
}

Step 3: Explore the Schema

The GraphQL explorer includes built-in documentation:

1. Click the Docs tab (book icon) on the right

2. Browse available queries, mutations, and types

3. Click any field to see descriptions and sub-fields

4. Use the Search feature to find specific schema elements

Step 4: Query Music Data

Now let’s get some actual music data with a track query:

query GetTrack {
  track(id: "B08F38BFYZ") {
    id
    title
    audioQualities
    contributingArtists {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

Try in GQL Console

This query fetches track information including title, audio qualities, and contributing artists.

Step 5: Use Query Variables

For dynamic queries, use variables instead of hardcoding values:

Query:

query GetTrack($trackId: String!) {
  track(id: $trackId) {
    id
    title
    audioQualities
    contributingArtists {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

Variables:

{
  "trackId": "B08F38BFYZ"
}

Try in GQL Console

Add variables in the Query Variables panel at the bottom of the explorer.

Common Query Patterns

Pagination

Most list fields support cursor-based pagination:

query GetArtistWithAlbums {
  artist(id: "B000QJJPUG") {
    id
    name
    albums(limit: 5) {
      edges {
        node {
          id
          title
        }
      }
      pageInfo {
        hasNextPage
        token
      }
    }
  }
}

Try in GQL Console

To view the next page of results, use the token value as a variable in a new query.

query GetArtistWithAlbums($token: String!) {
  artist(id: "B000QJJPUG") {
    id
    name
    albums(limit: 5, token: $token) {
      edges {
        node {
          id
          title
        }
      }
      pageInfo {
        hasNextPage
        token
      }
    }
  }
}

Try in GQL Console

Nested Queries

Fetch related data in a single request:

query GetArtistWithAlbumsAndTracks {
  artist(id: "B000QJJPUG") {
    id
    name
    albums (limit: 5) {
      edges {
        node {
          id
          title
          tracks {
            id
            title
            contributingArtists {
              edges {
                node {
                  id
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

Try in GQL Console

This single query fetches artist → albums → tracks → contributing artists in one request.

Troubleshooting

For help with common issues, see the Troubleshooting Guide or ask in #music-firefly-interest.

Next Steps

For Development

• Developer Onboarding - Set up your development environment

• Local Development - Run Firefly locally

• Contributing Guidelines - How to contribute

For Client Integration

• Insomnia Setup - Configure Insomnia for testing

• Query Examples - More query patterns

For Service Integration

• Client Onboarding - Connect your application

• Data Modeling Guide - Schema design best practices