Docs feedback: APIs are not fully documented if you do not document and fully specify the structure of the request and response.
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Problem to solve
All of the API documentation under https://docs.gitlab.com/ee/api/ is under-specified. In particular, there is no fully documented specification for the request, and there is no documented specification for the response, for any API documentation page that I have looked at.
Further details
A fully documented specification should include the following. Some of these points are already included in your API documentation; others are not.
- What is the general structure of the data. (Your docs already include this; URL request parameters for the request data, and JSON objects for the response data.)
- What are the pieces of data that are included in that structure. (You document this for the request data, but do not document this at all for the response data.) Note - this should include which pieces of data are optional and which are required.
- What are the possible values, or what are the domains of the values, for each piece of data. (Again, you document this for the request data, but do not document this for the response data.)
- What are the semantics of the values for each piece of data -- in other words, what does the data mean and how is it used. (You do not really document this at all.)
A series of examples, like what is included in your current API documentation, is not a fully documented specification. Those examples do not explain which data in the responses are optional (including which, if any, data may not appear int he response, and if there are any pieces of data which may appear but are not shown in the examples). They also do not document the possible values or domains of the response data. And neither for request nor response do they document the meaning of those values.