Team API Design Skill
When to Use This Skill
Use this skill when:
- Team Api Design tasks - Working on define team interfaces, contracts, and communication boundaries
- Planning or design - Need guidance on Team Api Design approaches
- Best practices - Want to follow established patterns and standards
Overview
Define clear team interfaces, contracts, and communication boundaries using Team API patterns.
MANDATORY: Documentation-First Approach
Before designing team APIs:
- Invoke
docs-managementskill for team interface patterns - Verify Team API concepts via MCP servers (perplexity)
- Base guidance on Team Topologies team API framework
What is a Team API?
TEAM API: The explicit interface a team exposes to other teams
┌─────────────────────────────────────────────────────────────────┐
│ TEAM API │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Code & │ │ Versioning │ │ Service │ │
│ │ Artifacts │ │ & Releases │ │ Catalog │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Wiki & │ │ Practices │ │ Ways of │ │
│ │ Docs │ │ & Runbooks │ │ Working │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Chat & │ │ Office │ │ Support │ │
│ │ Channels │ │ Hours │ │ Rotation │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
PURPOSE: Make team interactions explicit, predictable, and sustainable
Team API Components
1. Code and Artifacts
TECHNICAL INTERFACE:
Repositories:
• Main repo location (URL)
• Contributing guidelines
• Code review expectations
• Branch naming conventions
APIs:
• OpenAPI/AsyncAPI specs
• Authentication requirements
• Rate limits and quotas
• Deprecation policy
Artifacts:
• Package registry location
• Container image registry
• Artifact versioning scheme
• Release notes location
2. Versioning and Releases
RELEASE INTERFACE:
Versioning:
• Semantic versioning (MAJOR.MINOR.PATCH)
• Breaking change policy
• Deprecation timeline
• Migration guides
Release Schedule:
• Release cadence (weekly, bi-weekly, continuous)
• Release windows
• Hotfix process
• Rollback procedures
Compatibility:
• Supported versions
• EOL announcements
• Backward compatibility guarantees
• Forward compatibility approach
3. Documentation
KNOWLEDGE INTERFACE:
Team Wiki:
• Team overview and mission
• Architecture decisions (ADRs)
• Design documents
• Onboarding guides
API Documentation:
• Getting started guides
• API reference
• Code examples
• FAQ and troubleshooting
Operational Docs:
• Runbooks
• Incident response procedures
• Monitoring dashboards
• Alert explanations
4. Communication Channels
COMMUNICATION INTERFACE:
Asynchronous:
• Primary Slack/Teams channel
• Announcements channel
• Bug/issue tracker
• Email distribution list
Synchronous:
• Office hours schedule
• On-call rotation
• Escalation path
• Meeting cadence
Response Times:
• Slack: 4 business hours
• Issues: 1 business day
• Urgent: 1 hour
• Incident: 15 minutes
5. Service Level Expectations
SERVICE INTERFACE:
Availability:
• Target uptime (99.9%)
• Maintenance windows
• Planned downtime notice period
Performance:
• Latency targets (p50, p99)
• Throughput limits
• Error rate targets
Support:
• Business hours support
• On-call availability
• Incident severity levels
• Resolution time targets
Team API Template
# Team API: [Team Name]
## Team Overview
**Mission:** [One-sentence mission statement]
**Team Type:** [Stream-aligned | Platform | Enabling | Complicated-Subsystem]
**Bounded Context:** [Domain owned]
## Team Members
| Role | Name | Contact |
|------|------|---------|
| Tech Lead | [Name] | @handle |
| Product Owner | [Name] | @handle |
| Engineers | [Names] | @handles |
## What We Own
### Services
| Service | Description | Repository |
|---------|-------------|------------|
| [Name] | [Purpose] | [URL] |
### APIs
| API | Spec | Status |
|-----|------|--------|
| [Name] | [OpenAPI URL] | [Stable/Beta/Alpha] |
## How to Contact Us
### Asynchronous
- **Slack:** #team-[name]
- **Issues:** [Jira/GitHub project URL]
- **Email:** team-[name]@company.com
### Synchronous
- **Office Hours:** [Day/Time]
- **On-call:** [PagerDuty URL or rotation]
### Response Times
| Channel | Expected Response |
|---------|------------------|
| Slack | 4 business hours |
| Issues | 1 business day |
| Urgent Slack | 1 hour |
| Incidents | 15 minutes |
## How to Work With Us
### Requesting Changes
1. Open an issue in [repository]
2. Attend office hours to discuss
3. Submit PR following [contributing guide]
### Consuming Our APIs
1. Read [getting started guide]
2. Request API credentials via [process]
3. Follow [rate limiting guidelines]
### Escalation Path
1. Post in #team-[name]
2. Page on-call if urgent
3. Contact Tech Lead directly if blocked
## Service Level Expectations
### Availability
- **Target:** 99.9% uptime
- **Maintenance Window:** [Day/Time]
- **Notice Period:** 48 hours for planned downtime
### Performance
- **p50 Latency:** [X]ms
- **p99 Latency:** [X]ms
- **Error Rate:** <0.1%
### Support
- **Business Hours:** 9am-5pm [Timezone]
- **On-call Hours:** 24/7 for P1/P2
- **Holiday Coverage:** [Policy]
## Versioning and Releases
### Release Cadence
- **Frequency:** [Weekly/Bi-weekly/Continuous]
- **Release Day:** [Day]
- **Changelog:** [Location]
### API Versioning
- **Strategy:** [URL path | Header | Query param]
- **Breaking Change Notice:** [X weeks]
- **Deprecation Period:** [X months]
### Currently Supported Versions
| Version | Status | EOL Date |
|---------|--------|----------|
| v3 | Current | N/A |
| v2 | Maintenance | [Date] |
| v1 | Deprecated | [Date] |
## Documentation
### For Users
- [Getting Started Guide]
- [API Reference]
- [Code Examples]
- [FAQ]
### For Contributors
- [Contributing Guidelines]
- [Architecture Overview]
- [Development Setup]
- [Testing Guide]
### Operational
- [Runbooks]
- [Monitoring Dashboard]
- [Incident Response]
## Dependencies
### What We Depend On
| Team/Service | Type | Criticality |
|--------------|------|-------------|
| [Name] | [API/Library/Data] | [High/Medium/Low] |
### What Depends On Us
| Team/Service | Interface | Usage |
|--------------|-----------|-------|
| [Name] | [API/Event/Library] | [Description] |
## Roadmap
### Current Quarter
- [Initiative 1]
- [Initiative 2]
### Next Quarter
- [Planned work]
### Known Limitations
- [Limitation 1]
- [Limitation 2]
Team API Governance
Creating a Team API
TEAM API CREATION PROCESS:
1. DRAFT
□ Use template above
□ Fill in all sections
□ Get team consensus
2. REVIEW
□ Review with stakeholders
□ Validate with consumers
□ Check completeness
3. PUBLISH
□ Store in team wiki/repo
□ Register in service catalog
□ Announce to organization
4. MAINTAIN
□ Review quarterly
□ Update on changes
□ Gather feedback
Team API Maturity Levels
MATURITY MODEL:
LEVEL 1: BASIC
□ Team contact information exists
□ Primary service documented
□ Basic Slack channel
LEVEL 2: DEFINED
□ Full team API document
□ Response time expectations
□ Versioning policy defined
□ Basic SLEs documented
LEVEL 3: MEASURED
□ SLEs tracked and reported
□ Consumer feedback collected
□ Dependencies mapped
□ Regular API reviews
LEVEL 4: OPTIMIZED
□ Team API continuously improved
□ Automation for API updates
□ Consumer satisfaction tracked
□ Industry best practices adopted
Platform Team API Example
# Platform Team API: Developer Platform
## Mission
Enable stream-aligned teams to deliver software faster through
self-service infrastructure and golden paths.
## Team Type: Platform
## What We Provide
### Self-Service Capabilities
| Capability | Interface | Docs |
|------------|-----------|------|
| Container Deployment | CLI/Portal | [Link] |
| Database Provisioning | Terraform Module | [Link] |
| CI/CD Pipeline | Template | [Link] |
| Secrets Management | Vault API | [Link] |
### Golden Paths
| Path | Use Case | Guide |
|------|----------|-------|
| Web Service | Standard web APIs | [Link] |
| Event Consumer | Kafka consumers | [Link] |
| Scheduled Job | Batch processing | [Link] |
## Interaction Model
### X-as-a-Service (Default)
- Use our self-service capabilities
- Follow golden path documentation
- Submit issues for problems
- Attend office hours for questions
### Collaboration (By Request)
- Available for complex migrations
- Custom platform needs
- Time-boxed engagements
- Requires PM approval
## Office Hours
- **When:** Tuesdays 2-3pm, Thursdays 10-11am
- **Where:** #platform-office-hours Slack huddle
- **What:** Q&A, demos, troubleshooting
## Support Tiers
| Tier | Response | Example |
|------|----------|---------|
| P1 - Production Down | 15 min | Platform unavailable |
| P2 - Degraded | 1 hour | Slow deployments |
| P3 - Blocked | 4 hours | Can't provision resource |
| P4 - Question | 1 day | How to configure X |
Stream-Aligned Team API Example
# Team API: Payments Team
## Mission
Process payments reliably and securely for all commerce streams.
## Team Type: Stream-Aligned
## Bounded Context: Payment Processing
## What We Own
### Services
| Service | Purpose | SLE |
|---------|---------|-----|
| Payment Gateway | Process payments | 99.95% uptime |
| Refund Service | Handle refunds | 99.9% uptime |
| Fraud Detection | Real-time fraud | p99 < 50ms |
### APIs
| API | Description | Spec |
|-----|-------------|------|
| /payments | Create/query payments | [OpenAPI] |
| /refunds | Process refunds | [OpenAPI] |
### Events Published
| Event | Topic | Schema |
|-------|-------|--------|
| PaymentCompleted | payments.completed | [Avro] |
| RefundProcessed | payments.refunds | [Avro] |
## How to Integrate
### For Payment Processing
1. Read [integration guide]
2. Request sandbox credentials
3. Complete security review
4. Go-live checklist
### For Consuming Events
1. Subscribe to Kafka topic
2. Implement idempotent handler
3. Set up DLQ handling
4. Monitor consumer lag
## Constraints
- **PCI Compliance:** All integrations require security review
- **Rate Limits:** 1000 req/sec per client
- **Data Retention:** 7 years for transactions
Assessment Checklist
TEAM API HEALTH CHECK:
DISCOVERABILITY
□ Team API document exists and is findable
□ Registered in service catalog
□ Links work and content is current
COMPLETENESS
□ All sections filled in
□ Contact information accurate
□ Dependencies documented
□ SLEs defined
CLARITY
□ Non-team members can understand
□ No jargon or undefined terms
□ Clear call-to-action for consumers
□ Examples provided
MAINTENANCE
□ Last updated within 3 months
□ Regular review scheduled
□ Feedback mechanism exists
□ Ownership clearly assigned
EFFECTIVENESS
□ Consumers find what they need
□ Response times being met
□ Fewer repeated questions
□ Team satisfaction with API
Workflow
When designing team APIs:
- Audit Current State: What exists today? What's implicit?
- Identify Consumers: Who interacts with the team?
- Document Interface: Use template, fill completely
- Validate with Consumers: Does this meet their needs?
- Publish and Announce: Make it discoverable
- Measure and Iterate: Track effectiveness, improve
References
For detailed guidance:
Last Updated: 2025-12-26
Converted and distributed by TomeVault — claim your Tome and manage your conversions.