Assume that new API resources that we add are unstable
Problem
Typically, we add GraphQL resources without an Alpha designation, or we remove Alpha when we remove the Feature Flag.
But now we find that we can't align GraphQL object names without a lot of overhead. And relatedly, we can't move forward from a mostly broken REST endpoint with no known usage, without a lot of overhead.
- https://docs.gitlab.com/ee/development/api_styleguide.html#breaking-changes
- https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#breaking-changes
The benefit of these policies is that it encourages external actors to develop against the GitLab API.
The problem is we have proven that we sometimes want/need to make changes to API resources long after we add them. We don't have perfect foresight. The result is both lower velocity and more tech debt.
Proposal
- Don't add to the REST API until versioning is actually a thing.
- In new GraphQL API resources, always use the Alpha designation when possible.
- Open a follow up issue for each new resource, to track and discuss removing Alpha, scheduled for one year later.
- If someone, internal or external, says "Why is this resource Alpha? I want to develop against it." and the resource hasn't changed for a few milestones, then we or they could go ahead and remove the Alpha with a small MR.
Note: "Alpha" is distinct from "Feature Flagged". This proposal doesn't make a statement on feature flags. "Alpha" is a designation which advertises to potential API consumers that this GraphQL resource may change at any time.
To do
-
Mike: Consider opening a proposal against general GitLab development docs