API principles
Motivation
Proposal
- Every API that is likely to be consumed by 3rd party tools should be available over GitLab REST API
- GraphQL should be secondary when various GitLab products are the primary consumer of an API
- New REST APIs should follow the OpenAPI standard
- Interest in API design should be a requirement when hiring Product Designers (previous experience is a plus)
Not in scope
- The
CI_JOB_TOKEN
should be reviewed for its access rights and configuration
Current status
TL;DR: A mess
GitLab today offers 3 APIs:
The 3 APIs sometimes offer the same functionality, sometimes they do not. The OpenAPI is the least rich, and the most automatable.
API access and development is often an after-thought (example), this is reflected in missing functionalities and the missing product design around the CI_JOB_TOKEN
.
Pros and Cons
- REST is the industry standard for 3rd party shared APIs. The OpenAPI spec builds on top of REST and enables automatic consumption of the API. Enabling for example automatic SDK generation.
- GraphQL is recommended primarily for self-contained communication, like between a mobile-app and a backend server.
References
Discussion
Please, use the MR for all the discussion: gitlab-org/gitlab!74461 (closed)