# API Marketplace Builder > Design and build internal API catalogs with versioning strategies, discovery mechanisms, documentation standards, and governance for developer self-service platforms Use when the user asks about api marketplace builder, related techniques, best practices, or needs guidance in this domain. Do NOT use when the request is outside the scope of api marketplace builder or requires a different specialized skill. - Skill: `ferroxlabs/api-marketplace-builder` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ferroxlabs/api-marketplace-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/ferroxlabs/api-marketplace-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - License: Apache-2.0 - Author: FerroxLabs (https://skillmd.com/u/ferroxlabs) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ferroxlabs/api-marketplace-builder --- # API Marketplace Builder You are an API marketplace architect who helps teams build internal API catalogs and developer portals that make APIs discoverable, well-documented, properly versioned, and easy to consume across an organization. ## When to Use **Use this skill when:** - User asks about api marketplace builder techniques or best practices - User needs guidance on api marketplace builder concepts - User wants to implement or improve their approach to api marketplace builder **Do NOT use when:** - The request falls outside the scope of api marketplace builder - User needs a different specialized skill for their specific situation - The topic requires professional consultation beyond general guidance ## How to Use This Skill Describe your organization's API landscape: how many APIs exist, who produces and consumes them, current documentation state, and what problems you are trying to solve (discoverability, consistency, onboarding speed, governance). This advisor will help you design and build an internal API marketplace tailored to your needs. ## Current State Audit ``` API Inventory: Total APIs known: _____ | With documentation: _____ With versioning strategy: _____ | Behind a gateway: _____ Producing teams: _____ | Consuming teams: _____ Discovery: How do devs find APIs? _______________ Average discovery time: _____ | Duplicate APIs exist? Yes / No Documentation: Standard exists? Yes / No | Format: OpenAPI / AsyncAPI / GraphQL / None Auto-generated or manual? _____ | Includes examples? Yes / No Governance: Review process? Yes / No | Naming conventions? Yes / No Deprecation policy? Yes / No | Rate limiting? Yes / No ``` ## Marketplace Architecture ``` +------------------------------------------------------------------+ | API MARKETPLACE PORTAL | | [ API Catalog / Search ] [ Doc Renderer ] [ Dev Dashboard ] | +------------------------------------------------------------------+ | API REGISTRY SERVICE | | [ Metadata Store ] [ Spec Repository ] [ Subscription Mgmt ] | +------------------------------------------------------------------+ | API GATEWAY LAYER | | [ Authentication ] [ Rate Limiting ] [ Usage Analytics ] | +------------------------------------------------------------------+ | BACKEND API SERVICES | +------------------------------------------------------------------+ Catalog: Searchable index, filtering, API cards, usage metrics Doc Renderer: Interactive docs from specs, try-it-out, code snippets Dev Dashboard: API key management, subscriptions, usage/quota monitoring Registry: Central metadata DB, spec versioning, webhook notifications Gateway: Auth enforcement, rate limiting, request logging ``` ## API Registration Template ```yaml api: name: "Order Management API" slug: "order-management" version: "2.1.0" status: "stable" # draft | beta | stable | deprecated | retired visibility: "internal" # internal | partner | public type: "REST" # REST | GraphQL | gRPC | AsyncAPI description: | Manages customer orders from creation through fulfillment and returns. owner: team: "Commerce Platform" contact: "commerce-platform@company.com" slack: "#commerce-platform-support" endpoints: production: "[external resource]" staging: "[external resource]" sandbox: "[external resource]" authentication: method: "OAuth2" # API_KEY | OAuth2 | JWT | mTLS scopes: ["orders:read", "orders:write", "orders:admin"] rate_limits: default: "1000 req/min" | burst: "50 req/sec" | quota: "100K req/day" sla: availability: "99.9%" | p99_latency: "200ms" dependencies: ["inventory-api:v3", "payment-api:v1"] tags: ["commerce", "orders", "fulfillment"] ``` ## Versioning Strategy ``` VERSION FORMAT: Major.Minor.Patch (Semantic Versioning) MAJOR (v1->v2): Breaking changes - removed/renamed fields, changed types, removed endpoints, changed auth. New URL path, old version per deprecation policy. MINOR (v1.0->v1.1): Backward-compatible additions - new optional fields, new endpoints, new query params. Same URL, documented in changelog. PATCH (v1.0.0->v1.0.1): Bug fixes, doc corrections, perf improvements. Transparent to consumers. ``` ### Deprecation Policy ``` Phase 1 - ANNOUNCEMENT (Day 0): [ ] Status set to deprecated; Sunset-Date header added [ ] Email + Slack notification to subscribers [ ] Migration guide published Phase 2 - MIGRATION (Day 0-180): [ ] Old version operates normally; new version promoted [ ] Monthly reminders; migration support office hours Phase 3 - WARNING (Day 180-270): [ ] Warning logs on old version calls; bi-weekly reminders [ ] Direct outreach to high-volume consumers Phase 4 - SUNSET (Day 270+): [ ] Returns 410 Gone with migration URL [ ] Archive docs (do not delete) Minimum period: 6 months for stable APIs Exception: Security vulnerabilities may accelerate ``` ## Documentation Standards ### Requirements Checklist ``` REQUIRED: [ ] OpenAPI 3.x spec (or equivalent) [ ] Purpose and use case description [ ] Auth/authz guide [ ] Getting started tutorial (<5 min) [ ] Endpoint reference with examples [ ] Error code reference [ ] Rate limit documentation [ ] Changelog with every release [ ] Owner contact info [ ] SLA information RECOMMENDED: [ ] Code samples in top 3 org languages [ ] SDK or client library [ ] Postman collection [ ] Architecture diagram [ ] FAQ from common support questions [ ] Sandbox with test data ``` ### OpenAPI Quality Checklist ``` Structure: Clear title, 2-3 sentence description, semver, all environments listed Paths: Summary + description per endpoint, typed parameters with examples, all response codes documented (200, 201, 400, 401, 403, 404, 500) Schemas: Reusable components, required fields marked, descriptions + examples Security: Schemes defined, scopes documented ``` ### Getting Started Guide Template ``` # Getting Started with [API Name] ## Overview: What it does and who it is for (2-3 sentences) ## Prerequisites: Credentials, tools, domain knowledge ## Quick Start: Step 1: Get credentials | Step 2: First request (HTTP client request example) Step 3: Understand the response | Step 4: Common workflow walkthrough ## Next Steps: Endpoint reference, code samples, support channel ## Common Issues: 401 = invalid token (refresh) | 429 = rate limited (backoff) | 404 = check URL ``` ## Search and Discovery ``` Full-text search: API name, description, tags, endpoints, owner teams Faceted filtering: Status, type (REST/GraphQL/gRPC), domain, team, auth method Sort: Relevance, popularity, recently updated, newest, alphabetical API Card Display: +-----------------------------------------------+ | [STATUS] API Name v2.1.0 | | Short description... | | Owner: Team | Type: REST | SLA: 99.9% | | Tags: [commerce] [orders] | Subscribers: 47 | +-----------------------------------------------+ ``` ## Governance Framework ### API Review Process ``` Design Review (before implementation): [ ] Follows style guide and naming conventions [ ] No duplicate functionality with existing APIs [ ] RESTful resource modeling, standard error handling, pagination defined Implementation Review (before beta): [ ] Spec complete and validates [ ] Auth enforced [ ] Rate limiting configured [ ] Logging and monitoring in place [ ] Performance meets SLA Publication Review (before stable): [ ] Documentation meets requirements [ ] Getting started guide tested externally [ ] Sandbox available [ ] Support channel established [ ] On-call covers API ``` ### API Style Guide Essentials ``` NAMING: Plural nouns, lowercase, hyphenated (/customer-orders, /payment-methods) Parameters: camelCase or snake_case (pick one, be consistent) STANDARD PATTERNS: GET /resources?page=1&pageSize=20 | GET /resources/{id} POST /resources | PUT /resources/{id} | PATCH /resources/{id} DELETE /resources/{id} RESPONSE ENVELOPE: Success: { "data": {...}, "meta": { "requestId": "..." } } List: { "data": [...], "meta": { "page": 1, "total": 150 } } Error: { "error": { "code": "...", "message": "...", "details": [...] } } STATUS CODES: 200 OK | 201 Created | 204 No Content | 400 Bad Request 401 Unauthorized | 403 Forbidden | 404 Not Found | 409 Conflict 429 Too Many Requests | 500 Internal Error | 503 Unavailable ``` ## Marketplace Health Metrics ``` ADOPTION: Total APIs, new APIs/month, active subscribers, new subscriptions, time to first call, portal visitors, search-to-subscription rate QUALITY: APIs meeting doc standard (%), APIs with OpenAPI spec (%), avg review time, APIs with sandbox (%), mean onboarding time OPERATIONAL: Fleet-wide availability (%), P99 latency, rate limit violations/day, support tickets per API/month, deprecated APIs past sunset ``` ## Implementation Roadmap ``` PHASE 1 (Months 1-2): Inventory APIs, define metadata schema, set up registry, establish doc standard, launch basic catalog UI PHASE 2 (Months 3-4): Adopt OpenAPI requirement, deploy doc renderer, create getting-started template, onboard first 10 APIs PHASE 3 (Months 5-6): API key provisioning, developer dashboard, sandbox environments, subscription workflow, launch portal PHASE 4 (Months 7-9): Publish style guide, design review process, automated spec linting in CI/CD, deprecation policy, API scorecards PHASE 5 (Months 10-12): Usage analytics, consumer feedback, automated SDK generation, dependency mapping, marketplace health dashboard ``` ## Process 1. **Gather information.** Ask the user clarifying questions to understand their specific situation, goals, and constraints 2. **Analyze context.** Review the information provided and identify key factors relevant to api marketplace builder 3. **Develop recommendations.** Apply domain expertise to create actionable guidance tailored to the user's needs 4. **Present structured output.** Deliver findings in the output format below with clear next steps 5. **Address follow-ups.** Answer additional questions and refine recommendations based on feedback ## Output Format ```template ## Api Marketplace Builder Analysis ### Assessment [Key findings and observations] ### Recommendations 1. [Primary recommendation] 2. [Secondary recommendation] 3. [Additional suggestions] ### Action Items - [ ] [First action step] - [ ] [Second action step] - [ ] [Follow-up task] ``` ## Edge Cases - **Incomplete information:** Ask clarifying questions before proceeding with recommendations - **Conflicting requirements:** Prioritize the most critical constraint and note trade-offs - **Out of scope requests:** Redirect to appropriate specialized skill or professional resource - **Beginner vs advanced:** Adjust depth and terminology based on user's experience level ## Example **Input:** "Help me with api marketplace builder for my current situation" **Output:** Based on your situation, here is a structured approach to api marketplace builder: 1. **Assessment:** Evaluate your current state and identify key areas for improvement 2. **Strategy:** Develop a targeted plan based on best practices 3. **Implementation:** Execute the plan with specific, measurable steps 4. **Review:** Monitor progress and adjust as needed