go-api-sdk-apple

Go API SDK for Apple Services

A collection of Go SDKs for interacting with Apple API services and device management infrastructure:

• iTunes Search API — search and lookup across the iTunes, App Store, iBooks Store, and Mac App Store
• Apple Business Manager / Apple School Manager API — device inventory and MDM server management
• Apple Update CDN — firmware discovery and IPSW download for macOS, iOS, and iPadOS

Features

• Clean, idiomatic Go API
• Fluent builder patterns for constructing API requests
• Comprehensive error handling
• Configurable logging with zap
• Automatic retries with configurable parameters
• Extensive test coverage
• Complete examples for all supported operations

Supported Services

iTunes Search API

Complete implementation of the iTunes Search API:

• Search for content across iTunes, App Store, iBooks Store, and Mac App Store
• Look up content by ID, UPC, EAN, ISRC, or ISBN
• Filter results by media type, entity, country, and more

Apple Business Manager / Apple School Manager API

Complete implementation of the Apple Business Manager API:

Devices API:

• Get organization devices with filtering and pagination
• Get detailed device information by serial number
• Support for all device types (iPhone, iPad, Mac, Apple TV, Apple Watch)

Device Management Services API:

• List device management services in an organization
• Get device serial numbers assigned to services
• Assign/unassign devices to/from management services
• Get device management service assignments and information
• Track device activity operations

Key Features:

• JWT authentication — built-in Apple JWT token generation and management
• Structured logging — comprehensive request/response logging with zap
• Type-safe structured response models
• Context-aware operations for timeouts and cancellation

Quick Start:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/deploymenttheory/go-api-sdk-apple/axm"
    "github.com/deploymenttheory/go-api-sdk-apple/axm/axm_api/devicemanagement"
    "github.com/deploymenttheory/go-api-sdk-apple/axm/axm_api/devices"
)

func main() {
    // Method 1: Direct client creation — parse private key from PEM
    privateKey, err := axm.ParsePrivateKey([]byte(privateKeyPEM))
    if err != nil {
        log.Fatalf("Failed to parse private key: %v", err)
    }

    c, err := axm.NewClient("your-key-id", "your-issuer-id", privateKey)
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

    // Method 2: From environment variables
    // c, err := axm.NewClientFromEnv()
    // Expects: APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_PRIVATE_KEY_PATH

    // Method 3: From file
    // c, err := axm.NewClientFromFile("key-id", "issuer-id", "/path/to/key.p8")

    ctx := context.Background()

    // Get organization devices
    response, _, err := c.AXMAPI.Devices.GetV1(ctx, &devices.RequestQueryOptions{
        Fields: []string{
            devices.FieldSerialNumber,
            devices.FieldDeviceModel,
            devices.FieldStatus,
        },
        Limit: 100,
    })
    if err != nil {
        log.Fatalf("Error getting devices: %v", err)
    }

    fmt.Printf("Found %d devices\n", len(response.Data))

    // Get device management services
    mdmServers, _, err := c.AXMAPI.DeviceManagement.GetV1(ctx, &devicemanagement.RequestQueryOptions{
        Limit: 10,
    })
    if err != nil {
        log.Fatalf("Error getting MDM servers: %v", err)
    }

    fmt.Printf("Found %d MDM servers\n", len(mdmServers.Data))
}

📖 Complete Quick Start Guide →

Apple Update CDN

Firmware discovery and IPSW download across macOS, iOS, and iPadOS — no authentication required.

The SDK spans three external APIs:

Firmware discovery (ipsw.me API):

• ListAllFirmwareV3 — all device platforms unfiltered
• ListAllMacFirmwareV3 / ListAllIOSFirmwareV3 / ListAllIPadOSFirmwareV3 — per-platform filtered lists
• ListUniqueMacFirmwareVersionsV3 / ListUniqueIOSFirmwareVersionsV3 / ListUniqueIPadOSFirmwareVersionsV3 — deduplicated versions sorted newest-first
• GetByDeviceV4 — firmware history for a specific model identifier (e.g. "Mac14,3", "iPhone15,2", "iPad14,4") with SHA-256 checksums

Apple GDMF (signed version feed):

• GetPublicVersionsV2 — Apple's authoritative list of currently-signed versions for macOS, iOS, and visionOS including posting/expiration dates and supported device lists

CDN utilities:

• ParseURL — parse an IPSW CDN URL into its structural components (no HTTP request)
• GetFileMetadataV1 — HEAD request returning SHA-1, SHA-256, file size, and last-modified without downloading the file
• DownloadFileV1 — streaming IPSW download with SHA-1/SHA-256 verification and progress callback

Quick Start:

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "github.com/deploymenttheory/go-api-sdk-apple/apple_update_cdn"
    "github.com/deploymenttheory/go-api-sdk-apple/apple_update_cdn/tools/download_progress"
)

func main() {
    c, err := apple_update_cdn.NewDefaultClient()
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
    defer c.Close()

    ctx := context.Background()

    // List all unique macOS firmware versions, newest first.
    versions, _, err := c.AppleUpdateCDNAPI.Firmware.ListUniqueMacFirmwareVersionsV3(ctx)
    if err != nil {
        log.Fatalf("Error listing firmware: %v", err)
    }

    fmt.Printf("Found %d unique macOS versions\n", len(versions))
    for _, fw := range versions[:3] {
        fmt.Printf("  %s (%s) signed=%v\n", fw.Version, fw.BuildID, fw.Signed)
    }

    // Download the latest signed macOS IPSW with a progress bar.
    latest := versions[0]
    destPath := filepath.Join(os.TempDir(), filepath.Base(latest.URL))

    bar := download_progress.New(os.Stderr)
    progressFn := func(written, total int64) {
        bar.Callback(filepath.Base(destPath))(written, total)
    }

    result, _, err := c.AppleUpdateCDNAPI.CDN.DownloadFileV1(ctx, latest.URL, destPath, progressFn)
    if err != nil {
        log.Fatalf("Download failed: %v", err)
    }

    fmt.Printf("\nDownloaded %.2f GB in %s — verified=%v\n",
        float64(result.BytesWritten)/1e9, result.Duration.Round(1e9), result.Verified)
}

Download behaviour:

• Issues a HEAD request first to obtain expected size and checksums
• Streams the response body directly to disk — the full file is never held in memory
• Computes SHA-1 and SHA-256 simultaneously during streaming via io.MultiWriter
• Removes the partial file and returns an error on checksum mismatch or GET failure
• Creates the destination directory automatically if it does not exist
• macOS IPSW files are typically 15–22 GB; ensure sufficient free space

Examples

The examples directory contains a runnable main.go for every SDK function:

examples/
├── axm/                    Apple Business Manager
│   ├── devices/
│   └── devicemanagement/
├── apple_update_cdn/       Apple Update CDN
│   ├── firmware/           ipsw.me firmware discovery
│   ├── gdmf/               Apple signed-version feed
│   └── cdn/                URL parsing, metadata, download
└── itunes_search/          iTunes Search API

Documentation

• Go Reference Documentation
• iTunes Search API Documentation
• Apple Business Manager API Documentation
• Apple Device Management Documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License.