Team API Template (Team Topologies)
A team's public interface: type, mission, owned services, versioning, channels, ways of working, roadmap, interaction modes
How to use: Use it for every team so others know what it owns and how to work with it; fill it together in about an hour. Start with team type, mission and owned services. The main pitfall is letting it go stale, so review it each quarter.
Preview
Team API: [Team name]
A team's public interface for the rest of the organisation: who the team is, its type and mission, what it owns, how its software is versioned and documented, how to reach it, how it works, what it is working on and how it interacts with other teams. Adapted from the Team API template by Team Topologies (CC BY-SA 4.0). Replace every
[bracketed]value and every row marked Example. Worked examples use a payments platform team.
| Field | Value |
|---|---|
| Date | YYYY-MM-DD |
| Team name | [Payments Platform] |
| Team focus | [Reliable payment acceptance and payouts for all product teams] |
| Team type | [Stream-aligned / Enabling / Complicated subsystem / Platform] |
| Part of a platform? | [Yes: Commerce Platform / No] |
| Team lead / contact | [@team-lead] |
| Version | [0.1] |
| Next review | YYYY-MM-DD |
1. Team identity and type
Team type: [Platform]
Why this type: [Example: We provide payment capabilities as self-service APIs to six stream-aligned teams. We do not own any customer-facing journey ourselves.]
Members and roles:
| Name | Role | Areas of depth |
|---|---|---|
| Example: @lead | Engineering lead | Payment provider integrations |
| Example: @pm | Product manager | Internal developer experience |
| Example: @eng1 | Engineer | Ledger, reconciliation |
| [Name] | [Role] | [Areas] |
2. Mission
[Example: Make it possible for any product team to take and refund payments safely in under a day of integration work, without needing to understand card schemes, providers or regulatory detail.]
Do other teams depend on us? [Yes: Checkout, Subscriptions, Marketplace, Mobile, Support tools, Finance reporting]
Service level expectations other teams have of us: [Example: Payment API availability 99.95% monthly; p95 latency 300 ms; breaking changes announced 6 months ahead; support response within 4 working hours.]
3. Services and products owned
| Item | Type | Consumers | Tier | Catalogue link |
|---|---|---|---|---|
| Example: payments-api | Service (REST) | Checkout, Subscriptions, Marketplace | Tier 1 | [Link] |
| Example: ledger-service | Service (gRPC) | Payments API, Finance | Tier 1 | [Link] |
| Example: payments-sdk-js | Library | Web and mobile teams | Tier 2 | [Link] |
| Example: settlement-reports | Data product | Finance | Tier 2 | [Link] |
| [Item] | [Service / Library / Data product / Tool] | [Consumers] | [Tier] | [Link] |
4. Versioning approach
| Item type | Versioning | Deprecation notice |
|---|---|---|
| Example: HTTP APIs | Major version in URL; additive changes released continuously | 6 months, Deprecation and Sunset headers |
| Example: Libraries | Semantic Versioning; changelog per release | One major version of overlap |
| Example: Events | Schema registry, backward-compatible evolution | 3 months for new major event type |
| [Item type] | [Approach] | [Notice] |
5. Documentation and wiki
| What | Where |
|---|---|
| Team home page | [Link] |
| API reference and guides | [Developer portal link] |
| Runbooks | [Link] |
| Architecture decision records | [Link] |
| Wiki search terms | [Example: "payments", "refunds", "PSP", "ledger"] |
6. Communication channels
| Purpose | Channel | Response expectation |
|---|---|---|
| Questions and help | Example: #payments-help chat channel | Within 4 working hours |
| Feature requests | Example: [Issue tracker] board "Payments intake" | Triaged weekly on Tuesday |
| Incidents | Example: Page payments-oncall via [paging tool] | 15 minutes, 24/7 |
| Announcements | Example: #payments-announce and monthly newsletter | n/a |
| Daily sync | Example: 09:30 local time; visitors welcome with notice | n/a |
7. Ways of working and practices
| Practice | How we do it |
|---|---|
| Planning cadence | Example: Two-week iterations; quarterly roadmap review open to consumer teams |
| Intake and prioritisation | Example: Requests scored on consumer impact and risk; decisions posted in intake board |
| Code contributions from other teams | Example: Welcome on payments-sdk-js; read CONTRIBUTING.md; pair with us for service changes |
| Engineering practices | Example: Trunk-based development, contract tests for every consumer, deploy many times a day |
| On-call | Example: Weekly rotation of 6 engineers; follow-the-sun with [other site] |
8. Current work and roadmap
| Horizon | Item | Impact on other teams |
|---|---|---|
| Now | Example: Add wallet payment methods to payments-api | Checkout can enable them with a config flag |
| Next quarter | Example: Retire payments-api v1 | Subscriptions and Marketplace must migrate |
| Later | Example: Multi-currency payouts | Marketplace sellers outside the EU |
| Cross-team improvement | Example: Shared contract-testing setup for all platform APIs | Other platform teams can reuse it |
| [Horizon] | [Item] | [Impact] |
9. Team interactions
9.1 Current interactions
| Team | Team focus | Interaction mode | Purpose | Duration |
|---|---|---|---|---|
| Example: Checkout | Purchase journey | X-as-a-service | Checkout consumes payments-api | Ongoing |
| Example: Marketplace | Seller onboarding and payouts | Collaboration | Design split payments for sellers together | Until YYYY-MM-DD (about 3 months) |
| Example: SRE Enablement | Reliability practices | Facilitating (they help us) | Adopt SLO-based alerting | 6 weeks |
| [Team] | [Focus] | [Collaboration / X-as-a-service / Facilitating] | [Purpose] | [Duration] |
9.2 Expected interactions in the near future
| Team | Team focus | Interaction mode | Purpose | Expected start |
|---|---|---|---|---|
| Example: Subscriptions | Recurring billing | Collaboration, then X-as-a-service | Design retry logic for failed renewals | Next quarter |
| [Team] | [Focus] | [Mode] | [Purpose] | YYYY-MM-DD |
The diagram shows the team's current interaction modes.
Standard and licence note
Adapted from the Team API template by Team Topologies (https://github.com/TeamTopologies/Team-API-template), © Team Topologies, licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/). Team types and interaction modes are concepts from Team Topologies by Matthew Skelton and Manuel Pais. This adapted template, with its added guidance and examples, is shared under CC BY-SA 4.0.
Related templates
API Versioning and Deprecation Policy Template
API lifecycle policy: versioning scheme, compatibility promises, breaking changes, timelines, Deprecation and Sunset headers
Architecture & System DesignAPI Design Guidelines Template (Company Style Guide)
Company API style guide: naming, methods, status codes, RFC 9457 errors, pagination, versioning, security, webhooks, governance
Architecture & System DesignEvent-Driven API Specification Template (AsyncAPI 3)
Async event contract: brokers, channels, operations, CloudEvents envelope, ordering, delivery, DLQ, schema evolution, AsyncAPI YAML