SportDevs Go SDK

This is a generated Go SDK for the SportDevs API. The SDK provides sport-specific clients for compile-time safety and type checking.

Table of Contents

• Installation
• Quick Start
• Architecture
• Available Sports
• Usage Examples
• API Reference
• Error Handling
• Best Practices

Installation

This SDK is a complete Go module with proper dependency management. You can integrate it in several ways:

Option 1: As a Submodule in Your Repository

# In your main project repository
git submodule add <your-sdk-repo-url> pkg/sportdevs-sdk
# Or copy the SDK directory into your project structure

# In your go.mod file:
replace sportdevs-sdk => ./pkg/sportdevs-sdk

Option 2: Direct Integration (Copy Files)

# Copy the generated .go files to your project
mkdir internal/sportdevs
cp sportdevs-sdk/*.go internal/sportdevs/
# Import: "your-project/internal/sportdevs"

Option 3: Local Module Development

# For local development/testing
cd sportdevs-sdk
go mod tidy  # Already done during generation

# In your main project go.mod:
replace sportdevs-sdk => ../path/to/sportdevs-sdk

Option 4: Published Module (Future)

# When published to a repository
go get your-org/sportdevs-sdk
# Import: "your-org/sportdevs-sdk"

Quick Start

Here's a simple example to get you started:

package main

import (
    "context"
    "fmt"
    "log"

    "sportdevs-sdk"  // or "your-project/internal/sportdevs" for direct integration
)

func main() {
    // Create a american-football client
    client, err := sportdevs.NewAmericanFootballClient("your-api-key")
    if err != nil {
        log.Fatal(err)
    }

    // Make an API call
    ctx := context.Background()
map[string]interface{}, err := client.GetAggNewsMatches(ctx, "", 0, 0, "")    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d results\n", len(map[string]interface{}))}

Architecture

The SDK is organized into six main files:

1. client.go - Core HTTP Client

Contains the base Client struct that handles:

• HTTP communication with the SportDevs API
• Authentication via API key
• Request/response serialization
• Base URL construction

2. sports.go - Sport-Specific Clients

Provides type-safe clients for each sport:

• AmericanFootballClient for american-football
• AussieRulesClient for aussie-rules
• BadmintonClient for badminton
• BandyClient for bandy
• BaseballClient for baseball
• BasketballClient for basketball
• BeachVolleyballClient for beach-volleyball
• CricketClient for cricket
• DartsClient for darts
• EsportsClient for esports
• FloorballClient for floorball
• FootballClient for football
• FutsalClient for futsal
• HandballClient for handball
• HockeyClient for hockey
• RugbyClient for rugby
• SnookerClient for snooker
• TableTennisClient for table-tennis
• TennisClient for tennis
• VolleyballClient for volleyball
• WaterpoloClient for waterpolo

Each sport client embeds the base Client and provides compile-time sport validation.

3. api.go - API Methods

Contains all the generated API methods organized by sport client. Each method:

• Takes a context.Context as the first parameter
• Accepts typed parameters for the API call
• Returns typed responses or errors

4. models.go - Data Models

Contains Go structs representing API response schemas:

• Generated from OpenAPI schemas
• Properly tagged for JSON marshaling/unmarshaling
• Type-safe field access

5. go.mod - Go Module Definition

Defines the module and its dependencies (standard library only).

6. README.md - This Documentation

Complete usage guide and API reference for the SDK.

Available Sports

This SDK supports the following sports:

• AmericanFootball (american-football) - NewAmericanFootballClient(apiKey)
• AussieRules (aussie-rules) - NewAussieRulesClient(apiKey)
• Badminton (badminton) - NewBadmintonClient(apiKey)
• Bandy (bandy) - NewBandyClient(apiKey)
• Baseball (baseball) - NewBaseballClient(apiKey)
• Basketball (basketball) - NewBasketballClient(apiKey)
• BeachVolleyball (beach-volleyball) - NewBeachVolleyballClient(apiKey)
• Cricket (cricket) - NewCricketClient(apiKey)
• Darts (darts) - NewDartsClient(apiKey)
• Esports (esports) - NewEsportsClient(apiKey)
• Floorball (floorball) - NewFloorballClient(apiKey)
• Football (football) - NewFootballClient(apiKey)
• Futsal (futsal) - NewFutsalClient(apiKey)
• Handball (handball) - NewHandballClient(apiKey)
• Hockey (hockey) - NewHockeyClient(apiKey)
• Rugby (rugby) - NewRugbyClient(apiKey)
• Snooker (snooker) - NewSnookerClient(apiKey)
• TableTennis (table-tennis) - NewTableTennisClient(apiKey)
• Tennis (tennis) - NewTennisClient(apiKey)
• Volleyball (volleyball) - NewVolleyballClient(apiKey)
• Waterpolo (waterpolo) - NewWaterpoloClient(apiKey)

Usage Examples

Creating Sport-Specific Clients

// AmericanFootball client
americanfootballClient, err := sportdevs.NewAmericanFootballClient("your-api-key")
// AussieRules client
aussierulesClient, err := sportdevs.NewAussieRulesClient("your-api-key")
// Badminton client
badmintonClient, err := sportdevs.NewBadmintonClient("your-api-key")

Making API Calls

ctx := context.Background()

// Get americanfootball aggnewsmatches
map[string]interface{}, err := americanfootballClient.GetAggNewsMatches(ctx, "", 0, 0, "")
if err != nil {
    return err
}
// Get aussierules aggnewsmatches
map[string]interface{}, err := aussierulesClient.GetAggNewsMatches(ctx, "", 0, 0, "")
if err != nil {
    return err
}
// Get badminton aggnewsmatches
map[string]interface{}, err := badmintonClient.GetAggNewsMatches(ctx, "", 0, 0, "")
if err != nil {
    return err
}

Working with Query Parameters

The SportDevs API uses PostgREST-style query operators. You may need to format parameters with operators:

// Exact match
result, err := client.GetMatches(ctx, "eq.123", 0, 10, "en")

// Greater than
result, err := client.GetMatches(ctx, "gt.100", 0, 10, "en")

// Like operation
result, err := client.GetTeams(ctx, "like.*United*", "", 0, 10, "en")

// In operation
result, err := client.GetPlayers(ctx, "in.(1,2,3)", "", 0, 10, "en")

Using Context for Timeouts

// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// API call will respect the timeout
result, err := client.GetMatches(ctx, "", 0, 10, "en")

API Reference

Common Parameters

Most API methods accept these common parameters:

• ctx context.Context - Request context for cancellation and timeouts
• offset int - Pagination offset (0-based)
• limit int - Maximum number of results to return
• lang string - Language code (e.g., "en", "es", "fr")

Sport-Specific Methods

AmericanFootball

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 47 more methods

AussieRules

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 45 more methods

Badminton

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCountries() - Countries
• ... and 31 more methods

Bandy

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCountries() - Countries
• ... and 25 more methods

Baseball

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 49 more methods

Basketball

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 58 more methods

BeachVolleyball

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCountries() - Countries
• ... and 28 more methods

Cricket

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 48 more methods

Darts

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCountries() - Countries
• ... and 40 more methods

Esports

• GetAggNewsMatches() - Agg News Matches
• GetClasses() - Classes
• GetCountries() - Countries
• GetCupBracket() - Cup Bracket
• GetLeagues() - Leagues
• ... and 42 more methods

Floorball

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCountries() - Countries
• ... and 34 more methods

Football

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 82 more methods

Futsal

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 48 more methods

Handball

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 55 more methods

Hockey

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 56 more methods

Rugby

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 54 more methods

Snooker

• GetAggNewsMatches() - Agg News Matches
• GetClasses() - Classes
• GetCountries() - Countries
• GetCupBracket() - Cup Bracket
• GetLeagues() - Leagues
• ... and 30 more methods

TableTennis

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCountries() - Countries
• ... and 38 more methods

Tennis

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCountries() - Countries
• ... and 45 more methods

Volleyball

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCoaches() - Coaches
• ... and 46 more methods

Waterpolo

• GetAggNewsMatches() - Agg News Matches
• GetArenas() - Arenas
• GetArenasByCountry() - Arenas By Country
• GetClasses() - Classes
• GetCountries() - Countries
• ... and 40 more methods

Response Types

Most methods return one of:

• []map[string]interface{} - For list endpoints
• map[string]interface{} - For single resource endpoints
• Typed structs (when available in models.go)

Error Handling

The SDK provides detailed error information:

result, err := client.GetMatches(ctx, "", 0, 10, "en")
if err != nil {
    // Handle different types of errors
    switch {
    case strings.Contains(err.Error(), "context deadline exceeded"):
        // Timeout error
        fmt.Println("Request timed out")
    case strings.Contains(err.Error(), "401"):
        // Authentication error
        fmt.Println("Invalid API key")
    case strings.Contains(err.Error(), "404"):
        // Not found
        fmt.Println("Resource not found")
    default:
        // Other errors
        fmt.Printf("API error: %v\n", err)
    }
}

Best Practices

1. Use Appropriate Sport Clients

// Good: Type-safe and clear intent
americanfootballClient, _ := sportdevs.NewAmericanFootballClient(apiKey)

// Avoid: Using wrong sport client for your data

2. Handle Contexts Properly

// Good: Proper context usage
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

result, err := client.GetMatches(ctx, "", 0, 10, "en")

3. Implement Pagination

// Good: Paginate through large result sets
const pageSize = 100
offset := 0

for {
map[string]interface{}, err := client.GetAggNewsMatches(ctx, "", offset, pageSize, "")    if err != nil {
        return err
    }

    if len(map[string]interface{}) == 0 {
        break // No more results
    }

    // Process map[string]interface{}
    for _, item := range map[string]interface{} {
        // Process each item
    }
    offset += pageSize
}

4. Use Query Operators Correctly

// Good: Proper PostgREST operators
result, err := client.GetTeams(ctx, "eq.123", "", 0, 10, "en")        // Exact match
result, err := client.GetTeams(ctx, "like.*Arsenal*", "", 0, 10, "en") // Pattern match
result, err := client.GetTeams(ctx, "in.(1,2,3)", "", 0, 10, "en")     // In list

5. Reuse Clients

// Good: Create once, reuse multiple times
client, err := sportdevs.NewAmericanFootballClient(apiKey)
if err != nil {
    return err
}

// Reuse for multiple calls
map[string]interface{}, _ := client.GetAggNewsMatches(ctx, "", 0, 0, "")
map[string]interface{}, _ := client.GetArenas(ctx, "", "", 0, 0, "")
map[string]interface{}, _ := client.GetArenasByCountry(ctx, "", 0, 0, "")

Configuration

Go Module

The SDK is a self-contained Go module with the following characteristics:

• Module name: Configurable (defaults to sportdevs-sdk)
• Go version: 1.19+
• Dependencies: Standard library only
• Auto-generated: go.mod and go.sum are managed automatically during SDK generation

Base URL

The SDK automatically constructs the base URL using the pattern:

https://{sport}.sportdevs.com

Timeouts

The default HTTP client timeout is 30 seconds. You can customize this by modifying the client after creation:

client, _ := sportdevs.NewAmericanFootballClient(apiKey)
client.Client.Timeout = 60 * time.Second // 60 seconds

Custom HTTP Client

If you need to use a custom HTTP client (for proxies, custom certificates, etc.), you can replace the default client:

client, _ := sportdevs.NewAmericanFootballClient(apiKey)
client.Client = &http.Client{
    Timeout: 45 * time.Second,
    Transport: customTransport,
}

Troubleshooting

Common Issues

1. "API key cannot be empty"

   • Ensure you're passing a valid API key when creating the client

2. "context deadline exceeded"

   • The request timed out. Consider increasing the timeout or checking network connectivity

3. "401 Unauthorized"

   • Your API key is invalid or expired

4. "404 Not Found"

   • The endpoint or resource doesn't exist for the specified sport

5. Empty results

   • Check your query parameters and ensure the sport supports the requested endpoint

Debug Mode

To debug API calls, you can log the full request URL by modifying the client's doRequest method or adding logging middleware.

Support

For API-specific questions, refer to the SportDevs API documentation. For SDK issues, check that your OpenAPI specification is up to date and regenerate the SDK if needed.

---

This SDK was generated automatically from the SportDevs OpenAPI specification. Do not edit the generated files manually.