API Vision

Attributes

Property	Value
Date Created	2022-02-07
Target End Date	TBD
Slack	#wg_api_vision (only accessible from within the company)
Google Doc	Working Group Agenda (only accessible from within the company)
Issue Board	Issue Board
Overview & Status	See Exit Criteria below

Goal

The GitLab API Vision Working Group aims to improve the current APIs and define their future evolution.

Overview

We don't have a cohesive view between the REST and GraphQL APIs. We specify that the GraphQL API is the primary means of interacting programmatically with GitLab, but we often don't follow this criteria. Both APIs cover a different set of features, but none is feature-complete.

Goals

This is a list of topics that we want to discuss:

Responsibilities, Directly Responsible Individual, and technical experts. At the moment, the Manage:Integrations group is the DRI of the APIs but there is also the @graphql-experts group.
General vision of the GitLab API:
- REST / GraphQL API consistency.
- REST first vs. GraphQL first vs. another approach.
- Define user personas and consumers: frontend, CLI tooling, etc.
Review APIs:
- General architecture.
- Permissions and scopes.
- Feature coverage.
- Performance.
Testing:
- Coverage.
- Automated testing.
- Tools (eg. Postman collections).
API deprecations lifecycle and strategy:
- REST v5 API or further iterations.
- GraphQL deprecation process.
API standards, including OpenAPI specification.
Documentation:
- Improve current documentation.
- Review the first-time API user experience.
- Automation of the documentation.
- Full catalog of all public and internal APIs.
Learning and contributions:
- Review contributors' documentation.
- Create learning paths for team members, especially about GraphQL.

Exit Criteria

The table below lists all exit criteria for the working group. This is the top-level epic.

#	Completed Date	Progress	DRI	Criteria
1	TBD	10%	@g.hickman	Define the vision of the GitLab API for the future years
2	TBD	0%	@alexkalderimis	Set the foundation of a cohesive development strategy going forward
3	TBD	0%		Capture work needed for next generation API
4	TBD	15%	@.luke	Clarify the lifecycle of the API
5	TBD	15%	@kpaizee	Improve the documentation of the API
6	TBD	20%	@arturoherrero	Create learning paths and content to contribute to the API
7	TBD	5%		Define minimum levels of performance and stability, with appropriate checks and monitoring
8	TBD	35%	@g.hickman	Refresh personas to account for users of our APIs

Roles and Responsibilities

Working Group Role	Username	Person	Title
Executive Stakeholder	@timzallmann	Tim Zallmann	Senior Director of Engineering, Dev
Facilitator	@arturoherrero	Arturo Herrero	Engineering Manager, Manage:Integrations
Facilitator	@g.hickman	Grant Hickman	Senior Product Manager, Manage:Integrations
Functional Lead	@.luke	Luke Duncalfe	Senior Backend Engineer, Manage:Integrations
Functional Lead	@alexkalderimis	Alex Kalderimis	Senior Backend Engineer, Manage:Integrations
Functional Lead	@axil	Achilleas Pipinellis	Senior Technical Writer, Enablement
Functional Lead	@Andysoiron	Andy Soiron	Senior Backend Engineer, Manage:Integrations
Member	@grzesiek	Grzegorz Bizon	Principal Engineer, Verify
Member	@f_caplette	Frédéric Caplette	Senior Frontend Engineer, Verify:Pipeline Authoring
Member	@bmarjanovic	Bojan Marjanovic	Senior Backend Engineer, Manage:Integrations
Member	@kerrizor	Kerri Miller	Senior Backend Engineer, Create:Code Review
Member	@lauraX	Laura Montemayor	Backend Engineer, Verify:Pipeline Authoring
Member	@nagyv-gitlab	Viktor Nagy	Senior Product Manager, Configure
Member	@kpaizee	Kati Paizee	Senior Technical Writer, Growth and Ecosystem
Member	@fabiopitino	Fabio Pitino	Staff Backend Engineer, Verify:Pipeline Execution
Member	@dstull	Doug Stull	Staff Fullstack Engineer, Growth:Expansion
Member	@ntepluhina	Natalia Tepluhina	Staff Frontend Engineer, Plan:Project Management
Member	@avielle	Avielle Wolfe	Backend Engineer, Verify:Pipeline Authoring