DevEx: API Platform (#200) · Epics · Developer Experience

DevEx: API Platform

This epic is the SSOT for ongoing and planned API Platform group work. Please find below the work that is currently in-progress. ## Hours Worked | Epic | Category | DRI | Total Hours | |------|----------|-----|-------------| | [API Platform - Business As Usual](https://gitlab.com/groups/gitlab-org/quality/-/epics/231) | ~"infra-category::KTLO" | @mwoolf | 30.0  | | [API - Security bug fixes](https://gitlab.com/groups/gitlab-org/quality/-/epics/260) | ~"infra-category::Tech Debt" | @pjphillips | 2.0  | | [Prevent REST Entity Exposure Growth](https://gitlab.com/groups/gitlab-org/-/epics/20829) | ~"infra-category::Internal Innovation" | @abignotti | 0.0 | | [API Platform tooling survey - FY26Q1](https://gitlab.com/groups/gitlab-org/quality/-/epics/352) | ~"infra-category::KTLO" | @mwoolf | 0.0 | | [Introduce Lifecycle Status to REST API](https://gitlab.com/groups/gitlab-org/quality/-/epics/316) | ~"infra-category::Customer Innovation" | @mwoolf | 0.0 | | [Support all Grape keywords](https://gitlab.com/groups/gitlab-org/quality/-/epics/321) | ~"infra-category::Internal Innovation" | @abignotti @vwolanyk | 14.0  | | [Burn down Redocly OpenAPI 3.0 specification errors and warnings](https://gitlab.com/groups/gitlab-org/quality/-/epics/363) | ~"infra-category::Tech Debt" | @abignotti @vwolanyk | 14.0  | ## Project Work ### :hourglass: Work In Progress These epics are currently in progress | **Topic** | **Start Date** | **Target End Date** | **Summary** | |-----------|----------------|---------------------|-------------| | [API Platform - Business As Usual](https://gitlab.com/groups/gitlab-org/quality/-/epics/231) @mwoolf (+0 participants) ~"group::api platform" | 2025-08-04 | 2026-06-05 | **2026-03-26**: `gitlab-grape-openapi` gem enhancements and Grape gem upgrade (in the monorepo) scoping have been the main focus this week. :clock1: **total hours spent this week by all contributors**: 30h :tada: achievements: - @vwolanyk added support to the `gitlab-grape-openapi` gem for `limit: validator` (https://gitlab.com/gitlab-org/gitlab/-/work_items/594035), making the OpenAPI3 spec easier to understand - @vwolanyk opened a MR to add support to the `gitlab-grape-openapi` gem for `example`/`examples` (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/228334) and to update the API style guide to document endpoint success response options (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/228720) - @abignotti completed the audit scoping the effort to upgrade `Grape` from 2.0 to 3.1 (https://gitlab.com/gitlab-org/gitlab/-/work_items/593466#note_3191482218) :issue-blocked: blockers: - None :arrow_forward: next: - Merge open MRs - Have the team review the plan to upgrade `Grape` from 2.0 to 3.1 and scope it in epics and issues _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/231#note_3192667236_  | | [API - Security bug fixes](https://gitlab.com/groups/gitlab-org/quality/-/epics/260) @pjphillips (+0 participants) ~"group::api platform" | 2025-09-01 | 2026-07-01 | **2026-03-26**: :clock1: **total hours spent this week by all contributors**: 2h _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/260#note_3192667296_  **Nested Epics: 1** • https://gitlab.com/groups/gitlab-org/quality/-/epics/314+ | | [Prevent REST Entity Exposure Growth](https://gitlab.com/groups/gitlab-org/-/epics/20829) @abignotti (+0 participants) ~"group::api platform" | 2026-03-03 | 2026-04-10 | **2026-03-26**: The original scope of the epic has been completed. An important but non urgent follow-up issue related to the RuboCop cop got added to this epic. :clock1: total hours spent this week by all contributors: 4 :tada: achievements: - RuboCop cop to block expose additions to 41 high-impact entities added (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/226073) - Best practices documentation for feature-bounded REST API entities added (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/226532) :issue-blocked: blockers: - :arrow_forward: next: - Start working on the follow-up to add a scheduled pipeline for detecting newly high-impact entities over time (https://gitlab.com/gitlab-org/gitlab/-/issues/594435) _Copied from https://gitlab.com/groups/gitlab-org/-/epics/20829#note_3192667327_  | | [API Platform tooling survey - FY26Q1](https://gitlab.com/groups/gitlab-org/quality/-/epics/352) @mwoolf (+0 participants) ~"group::api platform" | 2026-03-16 | 2026-04-06 | **2026-03-26**: :clock1: **total hours spent this week by all contributors**: Oh :tada: **achievements**: No significant updates this week, DRI on PTO _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/352#note_3192667393_  | | [Introduce Lifecycle Status to REST API](https://gitlab.com/groups/gitlab-org/quality/-/epics/316) @mwoolf (+0 participants) ~"group::api platform" | | 2026-04-08 | **2026-03-26**: :clock1: **total hours spent this week by all contributors**: Oh :tada: **achievements**: No significant updates this week, DRI on PTO :arrow_forward: **next**: * After company-wide deadline - copy all lifecycle statuses to grape definitions. * Burn down TODO list of new rubocop offenses * Create dynamic check to ensure _all_ endpoints have an endpoint. _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/316#note_3192667444_  | | [Support all Grape keywords](https://gitlab.com/groups/gitlab-org/quality/-/epics/321) @abignotti @vwolanyk (+0 participants) ~"group::api platform" | 2026-01-10 | 2026-03-31 | **2026-03-26**: :clock1: **total hours spent this week by all contributors**: 14h :tada: **achievements**: - Completed all work scoped for the team, now all Grape keywords that are used in our codebase are covered by our `gitlab-grape-openapi` OpenAPI3 generator gem. The remaining open issues are being worked on by student community contributors @abignotti is helping mentor :issue-blocked: **blockers**: - :arrow_forward: **next**: - Review the contributions from the mentees _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/321#note_3192667505_  | | [Burn down Redocly OpenAPI 3.0 specification errors and warnings](https://gitlab.com/groups/gitlab-org/quality/-/epics/363) @abignotti @vwolanyk (+0 participants) ~"group::api platform" | 2026-03-12 | 2026-04-17 | **2026-03-26**: Burn down all/most Redocly (industry standard API documentation tool) validation errors and warnings to get the OpenAPI 3.0 specification into the best possible shape by having it comply with Redocly's recommended configuration. :clock1: **total hours spent this week by all contributors**: 14 :tada: achievements: - @abignotti fixed all instances of the top 2 most common errors and has 3 MRs waiting for reviews each fixing each of the remaining 3 error classes (there were 5 in total to begin with) - @vwolanyk opened an MR to fix the top 2 most common warnings :issue-blocked: blockers: - :arrow_forward: next: - Merge the open MRs, which could take more than expected due to other priorities - Start working on other child issues. The most impactful issues are the ones already fixed or being worked on right now _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/363#note_3194110243_  | ### :arrow_forward: Next These are the epics we will be focusing on next | **Topic** | **Target Start Date** | **Summary** | |-----------|-----------------------|-------------| | [REST API Docs Production Readiness](https://gitlab.com/groups/gitlab-org/quality/-/epics/369) @cfeick (+1 participants) ~"group::api platform" | 2026-03-30 | | ### :stop_button: Triage Epics that are currently being triaged | **Topic** | **Summary** | |-----------|-------------| | [Establish API endpoint lifecycle policies](https://gitlab.com/groups/gitlab-org/quality/-/epics/269) ~"group::api platform" | | | [OpenAPI Annotations - REST Endpoint Tier](https://gitlab.com/groups/gitlab-org/quality/-/epics/366) ~"group::api platform" | | | [Enable API-First Development Through Enhanced Training and Documentation](https://gitlab.com/groups/gitlab-org/quality/-/epics/270) ~"group::api platform" | | | [Make OpenAPI 3.0 REST SSoT](https://gitlab.com/groups/gitlab-org/quality/-/epics/287) ~"group::api platform" | | ### :white_check_mark: Completed Work Items that have been completed <details> | **Topic** | **Started** | **Ended** | **Summary** | |-----------| ------------| ----------| ------------ | | [Create API team roadmap](https://gitlab.com/groups/gitlab-org/quality/-/epics/203) ~"group::api platform" | 2025-08-18 | 2025-09-24 | **2025-09-17**: Max and Chance presented the team and our roadmap at the Engineering All Hands, so I think we can consider this epic fully complete :tada: _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/203#note_2756017387_  | | [REST API Style Enforcement for the benefit of OpenAPI enforcement](https://gitlab.com/groups/gitlab-org/quality/-/epics/233) ~"group::api platform" | 2025-09-13 | 2026-01-09 | **2026-01-07**: :clock1: **total hours spent this week by all contributors**: 0 :tada: **achievements**: * See [closing statement](https://gitlab.com/groups/gitlab-org/quality/-/epics/233#note_2984959726) _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/233#note_2987487672_  | | [Implement OpenAPI 3.0 Spec Generation](https://gitlab.com/groups/gitlab-org/quality/-/epics/232) ~"group::api platform" | 2025-10-11 | 2025-11-21 | **2025-11-20**: :tada: **achievements**: This Epic can be closed, please see the [closing statement](https://gitlab.com/groups/gitlab-org/quality/-/epics/232#closing-statement)  | | [GraphQL Metadata Enforcement Initiative](https://gitlab.com/groups/gitlab-org/quality/-/epics/243) ~"group::api platform" | 2026-01-06 | 2026-01-26 | **2026-01-21**: :clock1: **total hours spent this week by all contributors**: 18 :tada: **achievements**: - @mwoolf wrote an uncharacteristically large amount of JavaScript this week. ([MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/218657)) - Once this MR is merged, we can close this epic and allow feature teams to backfill their own feature categories. - Filled in feature categories for the _most_ popular GraphQL queries. - Announced changes to engineering week-in-review. :issue-blocked: **blockers**: - None. :arrow_forward: **next**: - @mwoolf responding to frontend maintainer comments on the above MR. Merge it. Close the epic :tada: Update 2026-01-22: Engineering work nearing a close. New linting rules are enforced in the GitLab monolith and announcements across engineering have been very well received. | | [Deploy experimental documentation for OpenAPI v3.0 specification](https://gitlab.com/groups/gitlab-org/quality/-/epics/261) ~"group::api platform" | 2025-11-15 | 2026-03-19 | **2026-03-12**: :clock1: **total hours spent this week by all contributors**: 4 :tada: **achievements**: - Project complete **Closing Status** **Original Problem**: GitLab's REST API documentation was limited to manually maintained Markdown covering only a subset of the API. The incomplete OpenAPI 2.0 spec lacked EE endpoints and ability for interactivity, creating friction for customers, AI agents, and external teams trying to discover and build on GitLab's full API capabilities. **Changes Made**: - Generated a [valid OpenAPI 3.0](https://gitlab.com/groups/gitlab-org/quality/-/work_items/218) specification covering the entire REST API surface area, including EE endpoints - Deployed an experimental API reference using open source tooling [Scalar](https://github.com/scalar/scalar) - Established the [API Docs](https://gitlab.com/gitlab-com/gl-infra/api-docs) project for foundation **Impact**: The full GitLab REST API is now discoverable and explorable through an experimental interactive reference for the first time. A complete, machine-readable OpenAPI 3.0 spec will unlock the ability to render API lifecycle status on all endpoints using end-to-end automation. This experimental deployment validated adoption of OpenAPI and Scalar tooling for automated solution and provides the foundation for iterating on https://gitlab.com/groups/gitlab-org/quality/-/work_items/369+, which will continue next steps to complete branding styles, performance optimizations, and public launch preparation/comms. **Demo**: https://api-docs-a0ae81.gitlab.io Shout-out to `@mwoolf`, `@abignotti`, `@idurham`, `@kkloss` for their collaboration on this foundational work 🚀 --- **Please close this epic in the next Platforms Grand Review.** _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/261#note_3152601388_  | | [OpenAPI 3.0 Spec Bug Fixes/Polish required before Docs Launch](https://gitlab.com/groups/gitlab-org/quality/-/epics/285) ~"group::api platform" | 2025-11-19 | 2026-03-19 | **2026-03-12**: Focused on closing out the remaining issues and wrapping up this epic. :clock1: **total hours spent this week by all contributors**: 8 :tada: **achievements**: * Closed the last 3 remaining issues: * Closed [custom content types](https://gitlab.com/gitlab-org/gitlab/-/work_items/585182) and [missing param options](https://gitlab.com/gitlab-org/gitlab/-/work_items/591949), improving accuracy and consistency of the generated OpenAPI 3 specification * Completed [OpenAPI 3.0 spec validation](https://gitlab.com/gitlab-org/gitlab/-/work_items/591007): the spec is now valid according to Swagger CLI. Added stricter Redocly CLI validation in `gitlab-com/gl-infra/api-docs` and created a [follow-up epic](https://gitlab.com/groups/gitlab-org/quality/-/work_items/363) to burn down the remaining Redocly errors. Swagger and Redocly are two different tools/platforms related to OpenAPI that also validate OpenAPI specifications, just in different ways * The OpenAPI 3.0 specification is now valid and ready for the interactive docs launch :issue-blocked: **blockers**: * None :arrow_forward: **next**: * This epic is complete and ready to be closed in the next Grand Review _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/285#note_3152601440_  | | [OpenAPI 3.0 Specification Generation and Validation](https://gitlab.com/groups/gitlab-org/quality/-/epics/284) ~"group::api platform" | 2026-01-12 | 2026-02-06 | **2026-02-04**: :clock1: **total hours spent this week by all contributors**: 2 :tada: **achievements**: * Completed the task! Added automated tooling (rake tasks ran in local linters and in CI jobs) in the GitLab project to trigger the generation and validation of the OpenAPI 3.0 specification :issue-blocked: **blockers**: * :arrow_forward: **next**: * Epic can be closed by our Grand Reviewers! _Copied from https://gitlab.com/groups/gitlab-org/quality/-/epics/284#note_3056319803_  | </details> ### :rotating_light: Epics that need attention These linked epics are not in the correct state or missing a workflow label <details> | **Topic** | **Links** | **Reason** | |-----------|-----------|-------------| | [OpenAPI 3](https://gitlab.com/groups/gitlab-org/quality/-/epics/218) (+0) group::api platform | Labeling problem, epic has no workflow label | </details>

epic