search

grafana / oncall

Developer-friendly incident response with brilliant Slack integration
GNU Affero General Public License v3.0
3.46k stars 279 forks source link

HTTP API docs unclarities #1380

Open Dieterbe opened 1 year ago

Dieterbe commented 1 year ago

pages such as:

say things like "The following available filter parameters should be provided as GET arguments"

Does this mean the parameters must be provided, or that if they are provided, they must be provided as GET arguments? There's ways to be more clear here. Like "these parameters are mandatory or optional... only GET is supported, not POST", etc

Also it's unclear why i have to specify values like id, route_id, integration_id or state if i just want to get a list of alert groups. We should describe what these parameters are for, what legal values are, and what recommended or default values are.

Dieterbe commented 1 year ago

also https://grafana.com/docs/oncall/latest/oncall-api-reference/alertgroups/ mentions "state", but looks like that should be status?

Eve832 commented 1 year ago

Hi @alyssawada can you take a look at this please?

Dieterbe commented 1 year ago

Same issue for the shifts api:

https://grafana.com/docs/oncall/latest/oncall-api-reference/on_call_shifts/#list-oncall-shifts

this shows an example curl GET request without any parameters (only an auth header), and a response that includes multiple shifts with each their name and id.

But then it says this:

The following available filter parameters should be provided as GET arguments: name (Exact match) schedule_id (Exact match)

All the same questions apply here as well.