Docs feedback: Events documentation does not properly specify structure of response
https://docs.gitlab.com/ee/api/events.html
The documentation here:
-
Doesn't explain the purpose or format of any fields:
-
title
is alwaysnull
in the given examples with no explanation.
-
-
Doesn't explain what fields will be available under what conditions:
-
target_iid
exists sometimes (correction: I now realize this is because the IID is only applicable to certain targets where there is a mismatch - I suppose that's reasonable enough, but maybe this should at least be mentioned along with which target types it does exist for.) -
target_title
is sometimes null and sometimes not -
author_username
and theauthor
object'susername
property both exist under some conditions, but do not appear to be identical.
-
-
Doesn't document how the structure changes when certain Actions or Targets are being represented, or gets things wrong:
- possible values for
action_name
are not documented, and are not the same as possible request action types -
action_name
is shown as"pushed"
in one of the examples, but when I interact with this same API I receive"pushed to"
. -
target_type
isnull
sometimes... seems unreasonable. - Possible
target_type
values for the response are also not documented, although the request target types listed near the beginning of the documentation are similar (but downcased.)
- possible values for
I am making an application that displays a notification feed right now, and the lack of any real concrete specification for response data is making it incredibly difficult. I suggest that the structure of response data be made much clearer.
Edited by Ethan McTague