Api Marketplace Builder

---
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

```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