Documenting "simple" JSON fields returned by GitLab's v4 API and system hooks
Problem to solve
Documentation about the JSON responses from the GitLab API:
- Which fields are always present ("simple" fields) and which fields may not included for each API call.
- The type of each field in a JSON object: string, integer, a nested JSON object etc.
- Same for system hooks: GitLab sends system hooks JSON for specific events. What's the fields and what are their types?
Further details
When developing libraries for the GitLab API, it would be useful to know which fields are always present, and which are not, in the returned JSON objects. In addition, the type of each JSON field e.g. nested JSON objects, strings, integers, etc.
The API documentation always gives examples of the returned JSON, e.g. https://docs.gitlab.com/ee/api/projects.html#list-user-projects . That is, for each API resource address there’s a JSON example given in https://docs.gitlab.com/ee/api/, but I’m never sure if that’s representative of all possible JSON responses for an API query e.g. with different levels of permissions with an access token.
For example the documentation for
GET /projects
Says:
only public projects with “simple” fields are returned.
https://docs.gitlab.com/ee/api/projects.html#list-all-projects
It'd be very useful to know which fields the "simple" (always present?) are.
Proposal
It would be useful for developers to know the “simple” fields (i.e. the fields that will always be present) documented. Also, which of the JSON fields are optionals for each API response.
This question also applies to the system hooks. There is a JSON example for the system hook when a project is created, here: https://docs.gitlab.com/ee/system_hooks/system_hooks.html#hooks-request-example
For different events (project_create
, user_update_for_team
etc), is there documentation for simple and optional fields in the JSON, any nested JSON objects in the returned JSON for each of the events that the system hooks support?
Who can address the issue
Technical writers documenting the API.