# 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.

<!--
Guidance: How to use this template
- Fill it in as a team, in one session of about an hour. Disagreements
  about ownership or interaction modes are useful findings; record them.
- Publish it where other teams look first (team wiki home page, service
  catalogue group page) and link it from the team's chat channel topic.
- Review it every [quarter] and whenever ownership or interaction modes
  change. A stale Team API is worse than none.
- Keep cognitive load in mind: if the "owned" lists in section 3 are long
  and varied, raise it with leadership rather than hiding it.
-->

| 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

<!-- Guidance: The four team types: stream-aligned (owns a flow of change to a business stream), platform (provides internal services that reduce other teams' cognitive load), enabling (helps other teams adopt new capabilities, temporarily), complicated subsystem (owns a part needing deep specialist knowledge). Choose one primary type and justify it. -->

**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

<!-- Guidance: One or two sentences on what the team exists to achieve, written for other teams. Mistake: listing activities instead of the outcome. -->

[*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

<!-- Guidance: Everything the team owns and evolves: services, libraries, data products, pipelines, internal tools. If nobody else knows the team owns it, it belongs here. -->

| 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

<!-- Guidance: How consumers can tell whether a change will affect them. Link the API deprecation policy if one exists. -->

| 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

<!-- Guidance: Where to find things. Include search terms people actually use, because people search before they ask. -->

| 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

<!-- Guidance: How and when to reach the team. Separate routine requests from urgent incidents. -->

| 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

<!-- Guidance: What other teams should know about how you work, so they can plan with you. -->

| 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

<!-- Guidance: What the team is doing now and next, at a level other teams can plan against. Also list cross-team or organisational improvements the team is driving. -->

| 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

<!-- Guidance: The three interaction modes: collaboration (two teams work closely together for a limited time to discover something new), X-as-a-service (one team consumes what another provides with minimal collaboration), facilitating (one team helps another learn or adopt something). Each interaction should have a purpose and an expected duration. -->

### 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.

```mermaid
flowchart LR
  PAY["Payments Platform (platform)"]
  CHK["Checkout (stream-aligned)"]
  MKT["Marketplace (stream-aligned)"]
  SRE["SRE Enablement (enabling)"]
  PAY -->|"X-as-a-service"| CHK
  PAY <-->|"Collaboration"| MKT
  SRE -.->|"Facilitating"| PAY
```

## 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.