Team API Template (Team Topologies)

A team's public interface: type, mission, owned services, versioning, channels, ways of working, roadmap, interaction modes

架构与系统设计标准Team Topologies Team APICC BY-SA 4.0team api更新于 2026年10月20日

在编辑器中打开下载 .md

使用方法: 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.

预览

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.