Clarification Needed: `/iolink/v2/gateway/events` vs. `/iolink/v2/gateway/diagnosis`

[thbauer-pepperl-fuchs]

There appears to be overlap or unclear differentiation between two endpoints in the IO-Link Gateway API:

• /iolink/v2/gateway/events
• /iolink/v2/gateway/diagnosis

/iolink/v2/gateway/events

Description:
Each Gateway shall have an Event Log object containing the events of the devices, ports and the masters. The content of the Event Log can be read by getting the object "Gateway Event Log".

Additional Query Parameters:

• top (integer, query parameter)
  Parameter to select the oldest x events of the event buffer. top is mutually exclusive to bottom.

• bottom (integer, query parameter)
  Parameter to select the youngest x events of the event buffer. bottom is mutually exclusive to top.

/iolink/v2/gateway/diagnosis

Description:
Each event with a mode of "APPEARS" is considered as a pending event until the occurrence of a corresponding event with mode of "DISAPPEARS". Pending events must be provided regardless of the Event Log content.

My Question:

The Response Body in the examples looks similar between both endpoints.:

1. What is the specific use case for each endpoint?
2. When should developers use /events vs. /diagnosis?
3. Does /diagnosis only return "pending" events (those with mode="APPEARS" that haven't been matched with mode="DISAPPEARS")?
4. Does /events return the full event log regardless of pending status?

[roesekoSICKAG]

Discussion in WG meeting (2026-02-04):
The origin of this endpoint can be found here #149.

Regarding your questions:
What is the specific use case for each endpoint? -> To directly access the currently pending events.
When should developers use /events vs. /diagnosis? -> /events shows all occured events which appeared and might disappeared already.
Does /diagnosis only return "pending" events (those with mode="APPEARS" that haven't been matched with mode="DISAPPEARS")? -> Yes. This makes it easier to find and detect problems.
Does /events return the full event log regardless of pending status? -> Yes.

But you have a point that it is very confusing to have two endpoint for events and there is no direct releation between diagnosis and events.

Decision:
Have only one endpoint /events with an additional query parameter onlyPendingEvents.
Add a comment to the delete /events endpoint that pending events shall not be deleted.

[roesekoSICKAG]

Discussion in WG meeting (2026-02-24):
During the meeting the conflict with DELETE /events and how to handle "pending events" came up. The only solution for this issue would be to keep the /diagnosis endpoint as it is and improve the description.

[roesekoSICKAG]

Discussion in WG meeting (2026-03-16):
@roesekoSICKAG will change the PR and revert the changes.