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

What We Own

Services

APIs

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

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

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

What Depends On Us

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

Golden Paths

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

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

APIs

Events Published

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