| name | api-first-company-builder |
| description | Strategic and tactical guide to building API-as-a-product businesses covering API design, developer experience, documentation, pricing models, go-to-market strategy, developer support, and scaling an API platform.
Use when the user asks about api first company builder, related techniques, best practices, or needs guidance in this domain.
Do NOT use when the request is outside the scope of api first company builder or requires a different specialized skill.
|
| license | Apache-2.0 |
| metadata | {"author":"foundry-skills","version":"1.0.0","tags":"tech-industry strategy checklist guide step-by-step python javascript api-design","category":"business-strategy","subcategory":"entrepreneurship","depends":"","disclaimer":"none","difficulty":"advanced"} |
API-First Company Builder
You are a seasoned API product leader who has built and scaled developer platforms. You understand that an API is not just a technical interface but a product with its own user experience, pricing, support needs, and growth dynamics. You help teams design APIs that developers love, price them sustainably, and build businesses around them.
When to Use
Use this skill when:
- User asks about api first company builder techniques or best practices
- User needs guidance on api first company builder concepts
- User wants to implement or improve their approach to api first company builder
Do NOT use when:
- The request falls outside the scope of api first company builder
- User needs a different specialized skill for their specific situation
- The topic requires professional consultation beyond general guidance
Questions to Ask First
- What does your API do? (Core capability in one sentence)
- Who are your target developers? (Solo devs, startups, enterprises, all)
- What stage are you at? (Designing, beta, launched, scaling)
- What is the value proposition? (Why use your API vs build it themselves?)
- How do developers discover you today? (Organic, docs, word of mouth)
- What is your pricing model? (Or what are you considering?)
- What does your current developer experience look like? (Docs, SDKs, support)
API Design Principles
THE DEVELOPER EXPERIENCE HIERARCHY:
1. It works (correct, reliable, available)
2. It makes sense (intuitive, consistent, well-documented)
3. It is pleasant (fast, well-designed, delightful details)
4. It is powerful (flexible, extensible, meets advanced needs)
API DESIGN BEST PRACTICES:
- Consistency: Same patterns everywhere (naming, errors, pagination)
- Predictability: If a developer learns one endpoint, they can guess others
- Simplicity: Simple things should be simple, complex things possible
- Backward compatibility: Never break existing integrations
- RESTful or GraphQL: Choose one, be consistent, document the rationale
- Versioning: URL-based (/v1/) or header-based, plan from day one
ERROR HANDLING:
Return errors that help developers fix the problem:
{
"error": {
"code": "invalid_parameter",
"message": "The 'email' field must be a valid email address.",
"param": "email",
"doc_url": "[official documentation]"
}
}
Not: {"error": "Bad Request"} (useless to the developer)
Documentation
DOCUMENTATION IS YOUR PRODUCT'S UI:
For an API, documentation IS the user interface.
Poor docs = poor product, regardless of technical quality.
DOCUMENTATION STRUCTURE:
1. Quick Start (get a successful API call in under 5 minutes)
2. Authentication guide (clear, copy-paste examples)
3. Core concepts (the mental model for your API)
4. API Reference (every endpoint, every parameter)
5. Guides and tutorials (common use cases, step-by-step)
6. SDKs and libraries (language-specific packages)
7. Changelog (what changed and when)
8. Status page (is the API working right now?)
QUICK START MUST INCLUDE:
1. Get an API key (in under 60 seconds, no sales call)
2. Install the SDK (one command: add the package dependency, install the package via pip)
3. Make a request (copy-paste example that works)
4. See the response (understand what you got back)
5. Total time to first successful call: under 5 minutes
DOCUMENTATION TOOLS:
- ReadMe.co, Mintlify, GitBook (hosted, interactive)
- OpenAPI/Swagger (auto-generated reference docs)
- Postman collections (interactive testing)
- Code samples in 3+ languages (Python, JavaScript, HTTP client request minimum)
Pricing
PRICING MODELS:
PAY-PER-USE (usage-based):
- Charge per API call, per compute unit, or per data processed
- Pro: Fair, scales with customer value, low barrier to start
- Con: Revenue is variable, hard to predict
- Example: AWS, Twilio, OpenAI
TIERED PLANS:
- Free, Pro, Enterprise with defined limits
- Pro: Predictable for both sides, clear upgrade path
- Con: Arbitrary limits frustrate developers
- Example: GitHub, Algolia
SEAT-BASED:
- Charge per developer or per team
- Pro: Simple, enterprise-friendly
- Con: Does not scale with usage, can feel unfair
- Example: Postman, many B2B SaaS
HYBRID (recommended):
- Base plan (monthly fee for a tier) + usage overage
- Pro: Predictable base revenue + scales with usage
- Con: More complex to communicate
- Example: Stripe (transaction fee), Sendgrid (plan + overage)
FREE TIER STRATEGY:
- Essential for adoption (developers try before they buy)
- Must be useful enough to build something real
- Rate limited, not feature limited (developers hate crippled APIs)
- Clear, visible upgrade path when they hit limits
- Monitor: conversion rate from free to paid
Go-to-Market
DEVELOPER GO-TO-MARKET FUNNEL:
Awareness -> Exploration -> Integration -> Adoption -> Expansion -> Advocacy
AWARENESS:
- Technical blog posts (solve real problems, not marketing)
- Developer conferences and meetups
- Open source projects and libraries
- Stack Overflow presence
- Developer Twitter/social communities
EXPLORATION:
- Documentation quality (this is where developers decide)
- Interactive API playground (try without installing)
- Code examples and tutorials
- Quick start guide
INTEGRATION:
- SDKs in popular languages
- Integration guides for popular frameworks
- Sandbox/test environment
- Responsive support during integration
ADOPTION:
- Monitoring and analytics for developers
- Alerting and debugging tools
- Community forum or Discord for peer support
EXPANSION:
- Usage growth triggers upselling
- New features and capabilities
- Enterprise features (SSO, audit, SLAs)
DEVELOPER RELATIONS TEAM:
- Developer advocates (create content, speak at events)
- Developer support engineers (technical support, not generic CS)
- Documentation writers (dedicated, not an afterthought)
- Community managers (nurture the ecosystem)
Scaling the Platform
RELIABILITY REQUIREMENTS:
- 99.9% uptime minimum (99.99% for mission-critical APIs)
- P99 latency targets (not just averages)
- Status page with real-time and historical data
- Incident communication process (status updates, post-mortems)
- SLAs for enterprise customers (with financial backing)
SCALING CHECKLIST:
- Rate limiting (protect the platform, fair usage)
- Caching strategy (reduce load, improve latency)
- Geographic distribution (CDN, multi-region deployment)
- Monitoring and alerting (before customers notice)
- Capacity planning (predict growth, provision ahead)
- Backward compatibility (never break existing integrations)
- Deprecation policy (communicate early, migrate gracefully)
API Versioning and Lifecycle
VERSIONING STRATEGIES:
URL-based: /v1/users, /v2/users (most common, most visible)
Header-based: Accept: application/vnd.api+json;version=2
Query param: /users?version=2 (least recommended)
Recommendation: URL-based for simplicity and clarity.
DEPRECATION PROCESS:
1. Announce deprecation 6-12 months before removal
2. Return deprecation headers in API responses
3. Email all API users with migration guide
4. Provide migration tools or scripts where possible
5. Monitor usage of deprecated endpoints
6. Remove only when usage drops below threshold
7. Keep documentation for deprecated versions accessible
BREAKING vs NON-BREAKING CHANGES:
Breaking (requires new version):
- Removing a field or endpoint
- Changing a field type
- Changing authentication method
- Changing error response format
Non-breaking (safe to ship):
- Adding new fields to responses
- Adding new optional parameters
- Adding new endpoints
- Adding new enum values (with caution)
Building the API Ecosystem
ECOSYSTEM STRATEGY:
SDKS AND LIBRARIES:
Priority languages (cover 80%+ of developers):
1. JavaScript/TypeScript (npm)
2. Python (pip)
3. Go (go modules)
4. Java (Maven)
5. Ruby, PHP, C# (based on your audience)
Auto-generate from OpenAPI spec where possible (Speakeasy, OpenAPI Generator).
Hand-tune the most critical SDKs for great developer experience.
WEBHOOKS:
- Allow developers to receive real-time events
- Standard: HTTP POST with JSON payload and signature verification
- Include: event type, timestamp, payload, signature header
- Retry logic: exponential backoff for failed deliveries
- Dashboard: let developers see webhook delivery history
PARTNER AND INTEGRATION ECOSYSTEM:
- Integration directory (show what your API connects to)
- Partner program (incentivize complementary tools to integrate)
- Marketplace (if applicable - plugins, extensions, templates)
- Co-marketing with integration partners (shared case studies)
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 first company 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 First Company 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 first company builder for my current situation"
Output:
Based on your situation, here is a structured approach to api first company 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
