API Quick Start - Sports Buddies

🌟 Overview

This quick start guide will walk you through setting up your first Sports Buddies API integration. By the end, you'll be able to authenticate, make your first API call, and retrieve user data.

⏱️ Time to Complete

This guide should take approximately 10-15 minutes to complete, depending on your experience level.

📋 Prerequisites

Before you begin, make sure you have the following:

Sports Buddies Account: A registered account on the platform
API Access: Approved API access (contact us to request access)
Client Credentials: Your client ID and client secret
Development Environment: Your preferred programming language and tools

⚠️ Important Note

If you don't have API access yet, please contact us at api-access@joinsportsbuddies.app to request access.

🔑 Step 1: Get Your API Credentials

Request API Access

Contact our team to request API access for your application.

Email: api-access@joinsportsbuddies.app
Include your use case and expected volume
Specify which scopes you need
Provide your company/organization details

Receive Your Credentials

Once approved, you'll receive:

Client ID: Your unique application identifier
Client Secret: Your application secret (keep this secure!)
API Base URL: https://api.joinsportsbuddies.app
Scopes: Approved access levels for your application

⚙️ Step 2: Set Up Your Development Environment

Choose Your Programming Language

We provide SDKs and examples for several popular languages:

JavaScript/Node.js: npm install @sportsbuddies/api
Python: pip install sportsbuddies-api
iOS (Swift): Available via CocoaPods
Android (Kotlin): Available via Maven

For this guide, we'll use JavaScript/Node.js examples, but the concepts apply to all languages.

Install Dependencies

If you're using Node.js, install the required packages:

npm install @sportsbuddies/api axios dotenv

Create a .env file to store your credentials:

SPORTS_BUDDIES_CLIENT_ID=your_client_id_here
SPORTS_BUDDIES_CLIENT_SECRET=your_client_secret_here
SPORTS_BUDDIES_REDIRECT_URI=http://localhost:3000/callback
                    

🔄 Step 3: Implement OAuth 2.0 Flow

Create Authorization URL

First, create the authorization URL that users will visit:

const clientId = process.env.SPORTS_BUDDIES_CLIENT_ID;
const redirectUri = process.env.SPORTS_BUDDIES_REDIRECT_URI;
const state = Math.random().toString(36).substring(7);

const authUrl = `https://api.joinsportsbuddies.app/oauth/authorize?` +
  `client_id=${clientId}&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `response_type=code&` +
  `scope=read&` +
  `state=${state}`;

console.log('Visit this URL to authorize:', authUrl);
                    

Handle the Callback

When the user authorizes your app, they'll be redirected back with an authorization code:

// This would be in your web server callback handler
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;
  
  // Verify state parameter to prevent CSRF attacks
  if (state !== expectedState) {
    return res.status(400).send('Invalid state parameter');
  }
  
  // Exchange code for access token
  const tokenResponse = await exchangeCodeForToken(code);
  
  // Store the access token securely
  // Redirect user to success page
  res.redirect('/success');
});
                    

Exchange Code for Token

Exchange the authorization code for an access token:

async function exchangeCodeForToken(authorizationCode) {
  const response = await axios.post('https://api.joinsportsbuddies.app/oauth/token', {
    grant_type: 'authorization_code',
    client_id: process.env.SPORTS_BUDDIES_CLIENT_ID,
    client_secret: process.env.SPORTS_BUDDIES_CLIENT_SECRET,
    code: authorizationCode,
    redirect_uri: process.env.SPORTS_BUDDIES_REDIRECT_URI
  });
  
  return response.data;
}
                    

📡 Step 4: Make Your First API Call

Get User Profile

Now you can make authenticated API calls. Let's start by getting the user's profile:

async function getUserProfile(accessToken) {
  try {
    const response = await axios.get('https://api.joinsportsbuddies.app/v1/users/me', {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error fetching user profile:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
const userProfile = await getUserProfile(accessToken);
console.log('User Profile:', userProfile);
                    

🎉 Congratulations!

You've successfully made your first API call to Sports Buddies! The response will contain the user's profile information including their name, sports preferences, and other details.

🔍 Step 5: Explore More API Endpoints

Find Sports Matches

Use the BuddyMatch™ algorithm to find compatible sports buddies:

async function findMatches(accessToken, preferences) {
  try {
    const response = await axios.post('https://api.joinsportsbuddies.app/v1/matches/find', preferences, {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error finding matches:', error.response?.data || error.message);
    throw error;
  }
}

// Example usage
const matchPreferences = {
  sports: ['basketball', 'tennis'],
  skill_level: 'intermediate',
  max_distance: 25,
  availability: ['weekends', 'evenings']
};

const matches = await findMatches(accessToken, matchPreferences);
console.log('Found matches:', matches);
                    

Send Messages

Enable communication between users:

async function sendMessage(accessToken, recipientId, message) {
  try {
    const response = await axios.post('https://api.joinsportsbuddies.app/v1/messages/send', {
      recipient_id: recipientId,
      message: message,
      type: 'text'
    }, {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error sending message:', error.response?.data || error.message);
    throw error;
  }
}

// Example usage
const messageResult = await sendMessage(accessToken, 'user_123', 'Hey! Want to play basketball this weekend?');
console.log('Message sent:', messageResult);
                    

❌ Error Handling

Proper error handling is crucial for a production application. Here are some common scenarios:

async function makeApiCall(endpoint, accessToken, data = null) {
  try {
    const config = {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    };
    
    let response;
    if (data) {
      response = await axios.post(endpoint, data, config);
    } else {
      response = await axios.get(endpoint, config);
    }
    
    return response.data;
  } catch (error) {
    if (error.response?.status === 401) {
      // Token expired or invalid
      console.log('Token expired, refreshing...');
      const newToken = await refreshAccessToken(refreshToken);
      // Retry the request with new token
      return makeApiCall(endpoint, newToken, data);
    } else if (error.response?.status === 429) {
      // Rate limit exceeded
      const retryAfter = error.response.headers['retry-after'];
      console.log(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
      throw new Error('Rate limit exceeded');
    } else {
      console.error('API Error:', error.response?.data || error.message);
      throw error;
    }
  }
}
                    

🧪 Testing Your Integration

Before going to production, thoroughly test your integration:

Test Environment: Use our sandbox environment for testing
Test Users: Create test accounts with different permission levels
Error Scenarios: Test token expiration, rate limits, and invalid requests
Edge Cases: Test with various data formats and boundary conditions

🔧 Sandbox Environment

Use https://sandbox-api.joinsportsbuddies.app for testing. This environment has higher rate limits and pre-created test data.

🎯 Next Steps

Now that you have the basics working, here's what you can explore next:

Advanced Features

Webhooks: Receive real-time updates about user activities
Analytics: Access detailed usage and performance data
Batch Operations: Process multiple requests efficiently
Real-time Features: Implement live messaging and notifications

Production Deployment

Security Review: Ensure your implementation follows security best practices
Monitoring: Set up logging and monitoring for your API usage
Documentation: Document your integration for your team
Support Plan: Plan for handling API changes and updates

🆘 Support & Resources

Need help with your integration? We're here to support you:

API Documentation: Complete API Reference
Authentication Guide: Detailed OAuth 2.0 Guide
SDK Documentation: Official SDKs and Libraries
Developer Support: api-support@joinsportsbuddies.app
Community Forum: Developer Community
Status Page: API Status

🚀 Ready to Build?

You now have everything you need to start building amazing integrations with Sports Buddies! If you have questions or need help, don't hesitate to reach out to our developer support team.

Explore More Documentation

Discover other helpful guides and resources to get the most out of Sports Buddies.

🎯 Getting Started

Learn the basics of Sports Buddies, create your profile, and make your first connection.

Quick Start Guide Profile Setup Making Connections App Navigation

📱 User Guides

Master all the features and learn how to get the most out of Sports Buddies.

BuddyMatch™ Algorithm Messaging & Communication Events & Meetups Notifications & Settings

🛡️ Safety & Trust

Learn about our PlaySafe™ features, verification process, and how we protect our community.

VerifiedPlayer™ ID Verification PlaySafe™ Safety Features Reporting Issues ShowScore™ Rating System

🤝 Community

Understand our community guidelines, moderation policies, and how to be a great community member.

Community Guidelines Moderation Policies Best Practices Community Events

⚙️ API & Developers

Technical documentation for developers, integrations, and API access.

API Overview Authentication API Endpoints Webhooks

❓ Help & Support

Find answers to common questions and get help when you need it.

Frequently Asked Questions Troubleshooting Contact Support Send Feedback

📋 Policies

Read our terms of service, privacy policy, and other important legal documents.

🚀 API Quick Start