API Vision

Attributes

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

Roles and Responsibilities

View page source - Edit this page - please contribute.