Docs: New API documentation structure
Description
After reviewing the existing content to contribute to the API https://gitlab.com/gitlab-org/gitlab/-/issues/377952 and investigating what the competitors do https://gitlab.com/gitlab-org/gitlab/-/issues/353445#note_1155675954, we should improve our existing documentation.
Possible new structure:
-
API Docs. Update this page to a simple overview page. Update: this is now the top-level of the Develop section. -
REST API. New page !108215 (merged) -
Contribute to the REST API (new section, no page) -
Development guide, links to:
-
-
Run REST requests/Use the REST API. New page -
REST API resources -
Deprecations and removals -
OpenAPI. OpenAPI specification is based on the REST API, this should belong here. -
REST API examples. New page -
Create different examples
-
-
Life cycle page. v4 / v5. Deprecations/Removals. New page
-
-
GraphQL API -
Contribute to the GraphQL API (new section, no page) -
Development guide, links to:
-
-
Run GraphQL API queries and mutations -
GraphQL API reference -
GraphQL API examples. New page -
Removed items.
-
-
CI Lint API -
OAuth 2.0 identity provider API
-
Other items to consider
REST API deprecations are documented under Documentation
: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#deprecations
GraphQL API deprecations are documented under Development style guides
: https://docs.gitlab.com/ee/development/api_graphql_styleguide.html#deprecating-schema-items
- Should the REST API page be under
Development style guides
? Or should the GraphQL API deprecation info be on its own page under theDocumentation
section of the nav?
Edited by Kati Paizee