Downloads API - Metadata Endpoints

Downloads API - Metadata Endpoints New

Get information about plugin versions without downloading the actual files. Perfect for checking versions, update detection, and integration purposes.

Overview

Metadata endpoints return JSON data about plugin versions, allowing you to:

• Check available versions
• Detect updates
• Get version information
• Query compatibility
• Build version comparison tools

Get All Plugin Versions

Retrieve metadata for all available plugin versions.

Endpoint: GET /api/plugin-versions

Authentication: Not required (public endpoint)

Example Request

curl

curl "https://api.statsly.org/api/plugin-versions"

Example Response

response.json

{
  "versions": [
    {
      "id": "plugin-1234567890-abc123",
      "serverSoftware": ["PaperMC", "Spigot"],
      "pluginVersion": "1.0.0",
      "javaVersion": "17",
      "minecraftVersion": "1.20.1",
      "proxyVersion": null,
      "fileName": "Statsly-1.0.jar",
      "fileSize": 1024000,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "createdBy": "username",
      "createdByUser": {
        "id": "user-id",
        "username": "username",
        "image": "https://...",
        "nickname": null
      },
      "isLatest": {
        "PaperMC": true,
        "Spigot": false
      }
    }
  ],
  "lastUpdated": "2024-01-01T00:00:00.000Z"
}

Response Fields

• versions - Array of plugin version objects
• lastUpdated - ISO 8601 timestamp of last update

Get Latest Version Metadata

Get metadata for the latest plugin version without downloading the file.

Endpoint: GET /api/plugin-versions/latest/:serverSoftware

Authentication: Not required (public endpoint)

URL Parameters

• serverSoftware (required) - Server software name

Example Request

curl

curl "https://api.statsly.org/api/plugin-versions/latest/PaperMC"

Example Response

response.json

{
  "version": {
    "id": "plugin-1234567890-abc123",
    "serverSoftware": ["PaperMC", "Spigot"],
    "pluginVersion": "1.0.0",
    "javaVersion": "17",
    "minecraftVersion": "1.20.1",
    "proxyVersion": null,
    "fileName": "Statsly-1.0.jar",
    "fileSize": 1024000,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "createdBy": "username",
    "isLatest": {
      "PaperMC": true,
      "Spigot": false
    }
  }
}

Get Latest Version Metadata (with Java Version)

Get metadata for the latest plugin version for a specific server software and Java version.

Endpoint: GET /api/plugin-versions/latest/:serverSoftware/:javaVersion

Authentication: Not required (public endpoint)

URL Parameters

• serverSoftware (required) - Server software name
• javaVersion (required) - Java version

Example Request

curl

curl "https://api.statsly.org/api/plugin-versions/latest/PaperMC/17"

Example Response

Same format as the previous endpoint.

Data Structure

PluginVersion Object

types.ts

interface PluginVersion {
  id: string; // Unique identifier (e.g., "plugin-1234567890-abc123")
  serverSoftware: string[]; // Array of supported server software
  pluginVersion: string; // Semantic version (e.g., "1.0.0")
  javaVersion: string; // Java version ("8", "11", "17", "21")
  minecraftVersion?: string; // Minecraft version (for normal/folia servers)
  proxyVersion?: string; // Proxy version (for proxy servers)
  fileName: string; // Original filename
  fileSize: number; // File size in bytes
  createdAt: string; // ISO 8601 timestamp
  updatedAt: string; // ISO 8601 timestamp
  createdBy: string; // Username of uploader
  createdByUser?: { // User information (if available)
    id: string;
    username: string;
    image?: string;
    nickname?: string;
  };
  isLatest: { // Map of server software to latest flag
    [key: string]: boolean;
  };
}

Latest Version Logic

The “latest” version is determined automatically based on:

1. Server Software + Java Version combination
2. Most recent upload date (createdAt timestamp)

Each combination of Server Software + Java Version has exactly one “latest” version. Since a plugin version can support multiple server software types, the isLatest field is an object mapping each server software to a boolean indicating if it’s the latest for that specific software + Java version combination.

Tip

If you don’t specify a Java version, the API will return the most recent version for that server software, regardless of Java version. For best compatibility, specify your Java version explicitly.

Usage Examples

Check for Updates

check-update.py

import requests

# Get latest version metadata
response = requests.get("https://api.statsly.org/api/plugin-versions/latest/PaperMC")
data = response.json()

latest_version = data["version"]["pluginVersion"]
current_version = "1.0.0"  # Your current version

if latest_version != current_version:
    print(f"New version available: {latest_version}")
else:
    print("Already up to date!")

List All Versions

list-versions.js

async function listAllVersions() {
  const response = await fetch('https://api.statsly.org/api/plugin-versions');
  const data = await response.json();

  console.log(`Total versions: ${data.versions.length}`);

  data.versions.forEach(version => {
    console.log(`${version.pluginVersion} - ${version.serverSoftware.join(', ')} - Java ${version.javaVersion}`);
  });
}

Filter by Server Software

filter-versions.js

async function getVersionsForSoftware(serverSoftware) {
  const response = await fetch('https://api.statsly.org/api/plugin-versions');
  const data = await response.json();

  return data.versions.filter(v =>
    v.serverSoftware.includes(serverSoftware)
  );
}

Error Handling

HTTP Status Codes

• 200 - Success (JSON response returned)
• 404 - Not Found (no version available for the specified criteria)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error

Error Response Format

error.json

{
  "error": "No plugin version found for PaperMC"
}

Best Practices

Caching

• Cache version metadata to avoid unnecessary API calls
• Check for updates periodically (e.g., once per day)
• Store the latest version ID to detect updates
• Implement cache invalidation strategies

Performance

• Use specific endpoints when possible (latest vs all)
• Filter results client-side for better performance
• Implement request debouncing for frequent checks

Tip

Cache metadata responses for at least 5-10 minutes to reduce API calls while still getting relatively fresh data.

Next Steps

• Learn about Download Endpoints
• Check out Usage Examples
• Review Server Software Compatibility