Draft: Set REST as the primary API approach

What does this MR do and why?

Motivation

Proposal

1. Every API that is likely to be consumed by 3rd party tools should be available over GitLab REST API
2. GraphQL should be secondary when various GitLab products are the primary consumer of an API
3. New REST APIs should follow the OpenAPI standard
4. Interest in API design should be a requirement when hiring Product Designers (previous experience is a plus)

Not in scope

1. The CI_JOB_TOKEN should be reviewed for its access rights and configuration

Current status

TL;DR: A mess

GitLab today offers 3 APIs:

• REST
• GraphQL
• OpenAPI
• SCIM API - for system access - out of scope

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

• GraphQL API vision
• REST - GraphQL evaluation
• REST - product design example

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

• I have evaluated the MR acceptance checklist for this MR.

Closes gitlab-com/Product#3413 (closed)