https://your-portal.com/api/marketplace/v1 API Version: v1 Authentication: Bearer token or API key (for protected endpoints) ## Table of Contents 1. Authentication 2. Rate Limiting 3. Error Handling 4. Endpoints 5. Webhooks 6. SDKs ## Authentication Most read operations are public, but write operations require authentication. bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ https://your-portal.com/api/marketplace/v1/plugins ## Rate Limiting - Anonymous requests: 100 requests per hour - Authenticated requests: 1000 requests per hour - Enterprise: Custom limits available Rate limit headers are included in all responses: X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 2024-08-07T12:00:00Z ## Error Handling All errors follow a consistent format: json { "error": { "code": "PLUGIN_NOT_FOUND", "message": "Plugin with ID 'xyz' not found", "details": {} }, "timestamp": "2024-08-07T10:30:00Z", "requestId": "req_abc123" } Common error codes: - PLUGIN_NOT_FOUND - Plugin does not exist - UNAUTHORIZED - Authentication required - FORBIDDEN - Insufficient permissions - RATE_LIMITED - Too many requests - VALIDATION_ERROR - Invalid request parameters - INTERNAL_ERROR - Server error ## Endpoints ### List Plugins GET /plugins List all available plugins with filtering, sorting, and pagination. #### Query Parameters | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | page | integer | Page number (1-based) | 1 | | limit | integer | Results per page (1-100) | 20 | | search | string | Search term for name/description | - | | category | string | Filter by category | - | | tags | string | Comma-separated tags | - | | sort | string | Sort field: name, popularity, updated, rating | popularity | | order | string | Sort order: asc, desc | desc | | verified | boolean | Only verified plugins | - | | featured | boolean | Only featured plugins | - | | minRating | number | Minimum rating (0-5) | - | | compatibility | string | Backstage version compatibility | - | #### Response json { "data": [ { "id": "plugin_123", "name": "catalog-backend", "displayName": "Catalog Backend", "description": "Backend plugin for the catalog", "version": "1.2.3", "author": { "name": "Spotify", "email": "backstage@spotify.com", "url": "https://spotify.com" }, "category": "backend", "tags": ["catalog", "backend", "core"], "icon": "https://example.com/icon.png", "verified": true, "featured": false, "rating": { "average": 4.5, "count": 128 }, "downloads": 50000, "compatibility": { "backstage": "^1.35.0", "node": ">=18.0.0", "platform": ["linux", "darwin", "win32"] }, "pricing": { "model": "free" } } ], "pagination": { "page": 1, "limit": 20, "total": 450, "totalPages": 23, "hasNextPage": true, "hasPrevPage": false }, "links": { "self": "/api/marketplace/v1/plugins?page=1&limit=20", "next": "/api/marketplace/v1/plugins?page=2&limit=20", "last": "/api/marketplace/v1/plugins?page=23&limit=20" }, "metadata": { "version": "v1", "timestamp": "2024-08-07T10:30:00Z", "requestId": "req_abc123", "responseTime": 45 } } ### Get Plugin Details GET /plugins/{pluginId} Get detailed information about a specific plugin. #### Response json { "data": { "id": "plugin_123", "name": "catalog-backend", "displayName": "Catalog Backend", "description": "Backend plugin for the catalog", "longDescription": "Extended description with markdown support...", "version": "1.2.3", "author": { "id": "author_456", "name": "Spotify", "email": "backstage@spotify.com", "verified": true }, "category": "backend", "tags": ["catalog", "backend", "core"], "screenshots": [ "https://example.com/screenshot1.png", "https://example.com/screenshot2.png" ], "videos": ["https://youtube.com/watch?v=xyz"], "repository": "https://github.com/backstage/backstage", "documentation": "https://backstage.io/docs", "changelog": "https://github.com/backstage/backstage/releases", "license": "Apache-2.0", "verified": true, "featured": false, "rating": { "average": 4.5, "count": 128, "distribution": { "5": 75, "4": 35, "3": 12, "2": 4, "1": 2 }, "reviews": [ { "id": "review_789", "rating": 5, "title": "Excellent plugin!", "review": "Works perfectly with our setup...", "user": { "id": "user_101", "name": "John Doe", "avatar": "https://example.com/avatar.png" }, "createdAt": "2024-08-01T10:00:00Z", "helpful": 45 } ] }, "downloads": { "total": 50000, "monthly": 5000, "weekly": 1200, "daily": 180 }, "versions": [ { "version": "1.2.3", "releaseDate": "2024-08-01T00:00:00Z", "changelog": "Bug fixes and improvements", "compatibility": { "backstage": "^1.35.0" } } ], "dependencies": [ { "name": "@backstage/core", "version": "^1.35.0" } ], "configuration": { "schema": {}, "defaults": {}, "examples": [] }, "permissions": ["catalog.read", "catalog.write"], "features": [ "Automatic entity discovery", "Custom processors", "API integration" ], "support": { "email": "support@backstage.io", "documentation": "https://backstage.io/docs", "issues": "https://github.com/backstage/backstage/issues" }, "stats": { "stars": 25000, "forks": 5000, "issues": 234, "contributors": 450, "lastCommit": "2024-08-07T09:00:00Z" } }, "links": { "self": "/api/marketplace/v1/plugins/plugin_123", "install": "/api/marketplace/v1/plugins/plugin_123/install", "reviews": "/api/marketplace/v1/plugins/plugin_123/reviews", "versions": "/api/marketplace/v1/plugins/plugin_123/versions" } } ### Install Plugin POST /plugins/{pluginId}/install Install a plugin (requires authentication). #### Request Body json { "version": "1.2.3", "configuration": { "apiUrl": "https://api.example.com", "apiKey": "secret" }, "environment": "production", "namespace": "backstage-plugins", "deploymentStrategy": "blue-green", "autoStart": true } #### Response (202 Accepted) json { "data": { "installationId": "install_abc123", "pluginId": "plugin_123", "status": "in_progress", "message": "Installation of plugin 'catalog-backend' has been initiated", "details": { "version": "1.2.3", "environment": "production", "namespace": "backstage-plugins", "deploymentStrategy": "blue-green" }, "progress": { "current": 0, "total": 100, "percentage": 0, "currentStep": "Initializing installation" }, "estimatedTime": 180, "links": { "status": "/api/marketplace/v1/installations/install_abc123", "logs": "/api/marketplace/v1/installations/install_abc123/logs", "cancel": "/api/marketplace/v1/installations/install_abc123/cancel" } } } ### Check Installation Status GET /installations/{installationId} Get the status of a plugin installation. #### Response json { "data": { "installationId": "install_abc123", "pluginId": "plugin_123", "status": "completed", "progress": { "current": 100, "total": 100, "percentage": 100, "currentStep": "Installation completed" }, "startedAt": "2024-08-07T10:00:00Z", "completedAt": "2024-08-07T10:03:00Z", "duration": 180 } } ### Search Plugins POST /plugins/search Advanced search with complex filters. #### Request Body json { "query": "monitoring", "filters": { "categories": ["monitoring", "observability"], "minRating": 4, "maxPrice": 100, "compatibility": { "backstage": "^1.35.0", "node": ">=18.0.0" } }, "sort": { "field": "relevance", "order": "desc" }, "pagination": { "page": 1, "limit": 20 } } ### Plugin Statistics GET /plugins/{pluginId}/stats Get detailed usage statistics for a plugin. #### Response json { "data": { "usage": { "installations": 5000, "activeInstallations": 4500, "dailyActiveUsers": 10000, "apiCalls": { "daily": 1000000, "weekly": 7000000, "monthly": 30000000 } }, "performance": { "averageResponseTime": 145, "p95ResponseTime": 450, "p99ResponseTime": 890, "errorRate": 0.01, "availability": 99.95 }, "trends": { "installationGrowth": 15.5, "usageGrowth": 22.3, "ratingTrend": 0.2 } } } ## Webhooks Subscribe to plugin events for real-time notifications. ### Available Events - plugin.installed - Plugin successfully installed - plugin.updated - Plugin updated to new version - plugin.uninstalled - Plugin uninstalled - plugin.error - Plugin encountered an error - plugin.health_changed - Plugin health status changed ### Webhook Registration POST /webhooks json { "url": "https://your-server.com/webhook", "events": ["plugin.installed", "plugin.error"], "secret": "webhook_secret_key" } ### Webhook Payload json { "event": "plugin.installed", "timestamp": "2024-08-07T10:00:00Z", "data": { "pluginId": "plugin_123", "version": "1.2.3", "installationId": "install_abc123" }, "signature": "sha256=abc123..." } ## SDKs Official SDKs are available for popular languages: ### JavaScript/TypeScript bash npm install @backstage/marketplace-sdk typescript import { MarketplaceClient } from '@backstage/marketplace-sdk'; const client = new MarketplaceClient({ apiKey: 'YOUR_API_KEY', baseUrl: 'https://your-portal.com' }); // List plugins const plugins = await client.plugins.list({ category: 'monitoring', verified: true }); // Install a plugin const installation = await client.plugins.install('plugin_123', { version: '1.2.3', environment: 'production' }); ### Python bash pip install backstage-marketplace python from backstage_marketplace import MarketplaceClient client = MarketplaceClient( api_key='YOUR_API_KEY', base_url='https://your-portal.com' ) # List plugins plugins = client.plugins.list( category='monitoring', verified=True ) # Install a plugin installation = client.plugins.install('plugin_123', { 'version': '1.2.3', 'environment': 'production' }) ### Go bash go get github.com/backstage/marketplace-sdk-go go import "github.com/backstage/marketplace-sdk-go" client := marketplace.NewClient( marketplace.WithAPIKey("YOUR_API_KEY"), marketplace.WithBaseURL("https://your-portal.com"), ) // List plugins plugins, err := client.Plugins.List(&marketplace.ListOptions{ Category: "monitoring", Verified: true, }) // Install a plugin installation, err := client.Plugins.Install("plugin_123", &marketplace.InstallOptions{ Version: "1.2.3", Environment: "production", }) ## Support For API support and questions: - Documentation: https://your-portal.com/docs/api - GitHub Issues: https://github.com/your-org/portal/issues - Email: api-support@your-company.com