Skip to content

Latest commit

 

History

History
407 lines (299 loc) · 18.3 KB

teamapi.md

File metadata and controls

407 lines (299 loc) · 18.3 KB
Raw

TeamAPI Specification

Team Topologies Team Topologies is the leading approach to organizing business and technology teams for fast flow, providing a practical, step-by‑step, adaptive model for organizational design and team interaction. .

One of the concepts from Team Topologies is the introducation of a Team API which helps teams to capture and improve their clarity of purpose.

The TeamAPI Specification is an attempt at codifying the Team API template into a machine readable definition that can be can then be used to generate documentation and visualizations of how the teams within your organization are interacting and how that changes over time.

Table of Contents

Definitions

Stream Aligned Team

Stream-aligned teams should aim to produce a steady flow of feature delivery, with end-to-end responsibility for a service or application.

Platform Team

Platform teams provide the underlying internal services required by stream-aligned teams to deliver higher level services or functionalities, thus reducing extraneous cognitive load.

Enabling Team

Enabling teams help stream-aligned teams detect and acquire missing capabilities but do not own services themselves.

Complicated Subsystem Team

Complicated subsystem teams off-load work from stream-aligned teams on particularly complicated subsystems.

Facilitation

Facilitating is where one team helps another and is the main operating model for enabling teams. This mode is used to help clear impediments and help discover gaps or inconsistencies in existing components and services used by other teams. There should be a focus on the quality of interaction between other teams. Like the Collaboration mode, Facilitating is a temporary interaction mode - the interaction should generally last for no more than a few weeks.

Collaboration

Collaboration is where teams work closely with other teams with different skill sets for a defined period of time (usually a few weeks). This is typically used when a high degree of adaptability or discovery is needed.

X-as-a-service

X-as-a-service (XaaS) is a natural interaction model after collaboration has discovered suitable boundaries. XaaS provides clear ownership of a service with a smaller cognitive load for teams consuming the service. It is important that this interaction mode provides a good developer experience and the service being consumed should generally be managed as [part of] a product.

Specification

Format

The files describing team interactions in accordance with the TeamAPI Specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to represent a TAS (TeamAPI Specification) file.

For example, if a field is said to have an array value, the JSON array representation will be used:

{
   "field" : [...]
}

While the API is described using JSON it does not impose a JSON input/output to the API itself.

All field names in the specification are case sensitive.

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is recommended along with some additional constraints:

  • Tags MUST be limited to those allowed by the JSON Schema ruleset
  • Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset

File Structure

An TeamAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, Reference Objects are used.

By convention, the TeamAPI Specification (TAS) file is named TeamAPI.json or TeamAPI.yaml.

Schema

TeamAPI Object

This is the root document object for the API specification. It combines resource listing and API declaration together into one document.

Fixed Fields
Field Name Type Description
teamapi TeamAPI Version String Required. Specifies the TeamAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be major.minor.patch, where patch versions must be compatible with the existing major.minor tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding major.minor (1.0.*). Patch versions will correspond to patches of this document.
info Info Object Required. Core information about the team including their focus and fundamental team type.
channels [Channels Object] A list of any channels that can be used to contact the team.
searchTerms [Search Terms] Any terms specific to this team that people might use to search for.
platform Platform Object If this is present, indicates that this team is part of a wider platform.
services [Services Object] A list of any software, services or products that is currently owned by the team.
work Work Object Details of the type of work the team takes part in.
meetings [Meetings Object] A list of meetings that the team currently takes part in.
interactions [Interaction Object] Team interactions that the team currently take part in.
dependencies [Dependency Object] A list of other teams that the team have a dpendency on.

This object can be extended with Specification Extensions.

TeamAPI Version String

The version string signifies the version of the TeamAPI Specification that the document complies to. The format for this string must be major.minor.patch. The patch may be suffixed by a hyphen and extra alphanumeric characters.

A major.minor shall be used to designate the TeamAPI Specification version, and will be considered compatible with the TeamAPI Specification specified by that major.minor version. The patch version will not be considered by tooling, making no distinction between 1.0.0 and 1.0.1.

In subsequent versions of the TeamAPI Specification, care will be given such that increments of the minor version should not interfere with operations of tooling developed to a lower minor version. Thus a hypothetical 1.1.0 specification should be usable with tooling designed for 1.0.0.

Info Object

Core information about the team including their focus and fundamental team type

Fixed Fields
Field Name Type Description
name string Required. The name of the team.
focus string The core focus/goal of the team
type string stream-aligned, platform, complicated-subsystem, enabling.
Info Object Example
info:
  name: Example stream A
  focus: Core focus of the team
  type: stream-aligned

Channel Object

A channel that can be used to contact the team

Fixed Fields
Field Name Type Description
type string Required. The type of the communication channel.
name string Required. The name of the communication channel.
Channel Object Example
channels:
  - type: slack
    name: example-stream-a

Search Term Object

A term that can be used to find information about the team and it's products on an internal wiki or similar.

Fixed Fields
Field Name Type Description
term string Required. The searchable term.
Search Term Object Example
searchTerms:
  - term: Example team search term

Platform Object

If this is present, indicates that this team is part of a wider platform.

Fixed Fields
Field Name Type Description
$ref string Required. A reference to the team api for the platform team that this team is part of
Platform Object Example
platform:
  - $ref: https://github.com/example.com/example-platform-team/teamapi.yml

Service Object

Describes any software, services or products that is currently owned by the team.

Fixed Fields
Field Name Type Description
name string Required. The name of the software owned by this team
url string A url to documentation describing the software
versioning Versioning Object Details of the way in which this product is versioned
repository string A url to the repository containing source code for this service
Service Object Example
services:
  - name: Example Service A
    url: https://anexampleservice.com
    versioning:
      type: semantic
    repository: https://github.com/example.com/example-service-a

Versioning Object

Details of the way in which a service, subsystem or product is versioned.

Fixed Fields
Field Name Type Description
type string Required. The versioning strategy employed i.e. semantic etc
Versioning Object Example
versioning:
  type: semantic

Work Object

Details of the type of work the team takes part in.

Fixed Fields
Field Name Type Description
services Work Service Object A list of services, software, products that the team is currently working on
waysOfWorking Ways Of Working Object A list of the ways in which the team currently works
crossTeam CrossTeamWorkObject A list of the cross-team work or improvements that the team currently takes part in
Work Object Example
versioning:
  type: semantic

Work Service Object

Details of a service that the team is currently working on.

Fixed Fields
Field Name Type Description
name string The name of the service being worked on
$ref string A reference to the service being worked on
Work Service Object Example
work:
  services:
  - name: Improve the example service a
    $ref: https://github.com/example.com/example-service-a

Ways Of Working Object

Details of how a team is working.

Fixed Fields
Field Name Type Description
name string The name of the way of working
$ref string A reference to details about the way of working
Ways Of Working Object Example
work:

  waysOfWorking:
    - name: Lean
      $ref: https://example.internal-wiki.com/ways-of-working/lean

Meetings Object

Details of meetings that the team attends.

Fixed Fields
Field Name Type Description
purpose string The purpose of the meeting
dayOfWeek string The day of the week that the meeting takes place
timeOfDay string The time of day that the week the meeting takes place
durationMinutes integer The duration of the meeting in minutes
Meeting Object Example
meetings:
  - purpose: daily sync
    dayOfWeek: Wednesday
    timeOfDay: 09:00
    durationMinutes: 15

Interaction Object

Details of team interactions that the team currently take part in

Fixed Fields
Field Name Type Description
teamName string The name of the team being interacted with
purpose string The purpose of the interaction
startDate Date The date the interaction began
expectedDuration string The date the interaction began
expectedDurationUnit string One of Days, Weeks, Months
$ref string A reference to the team api of the interacting team
Interaction Object Example
interactions:
  - team-name: Example Platform Team
    mode: X-as-a-service
    purpose: The purpose of the interaction
    startDate: 01/01/2022
    expectedDuration: 3
    expectedDurationUnit: months
    $ref: https://github.com/example.com/example-platform-team/teamapi.yml
  - team-name: Automation Test Enabling Team
    mode: Facilitating
    purpose: Introduce automation tests into the example service
    startDate: unknown
    $ref: https://github.com/example.com/automation-test-team/teamapi.yml

Dependency Object

Details of dependencies on other teams that the team has

Fixed Fields
Field Name Type Description
teamName string The name of the dependent team
description string A description of the dependency
type string The type of the dependency. One of OK, Slowing or Blocking
$ref string A reference to the team api of the dependent team
Dependency Object Example
dependencies:
  - team-name: Example stream b
    description: We currently rely on example stream b to make changes to component X.
    type: Blocking
    $ref: https://github.com/example.com/example-stream-b-team/teamapi.yml
  - teamName: Example Platform Team
    description: We use the platform team to provide CI/CD services
    type: OK
    $ref: https://github.com/example.com/example-platform-team/teamapi.yml