| name | api-marketplace-builder |
| description | 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.
|
| license | Apache-2.0 |
| metadata | {"author":"foundry-skills","version":"1.0.0","tags":"devops cloud checklist template guide api-design testing performing-arts","category":"devops-cloud","subcategory":"cloud-infrastructure","depends":"","disclaimer":"none","difficulty":"beginner"} |
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
api:
name: "Order Management API"
slug: "order-management"
version: "2.1.0"
status: "stable"
visibility: "internal"
type: "REST"
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"
scopes: ["orders:read", "orders:write", "orders:admin"]
rate_limits:
default: "1000 req/min" | burst: "50 req/sec" | quota: "100K req/day"
sla:
[, ]
[, , ]
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
- Gather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
- Analyze context. Review the information provided and identify key factors relevant to api marketplace builder
- Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
- Present structured output. Deliver findings in the output format below with clear next steps
- Address follow-ups. Answer additional questions and refine recommendations based on feedback
Output Format
## 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:
- Assessment: Evaluate your current state and identify key areas for improvement
- Strategy: Develop a targeted plan based on best practices
- Implementation: Execute the plan with specific, measurable steps
- Review: Monitor progress and adjust as needed
