More documentation insufficiency: "components" field of incidents is not documented.

[Johnson Earls]

Along with many many other items, the "components" field of incidents is not documented.

• In the create-incident API call, what goes into the components field and what effect does it have?
• When retrieving an incident, what appears in the components field?
• What causes changes to the components field?

This type of thing is why you need to document the API specifications (which includes syntax and semantics), not just what appears to be a human readable version of swagger.

[Abhay Sarraf]

Hey @Johnson Earls 

G'Day hope you're doing well

The API works off of 2 fields for Component.

• component_ids - This tells Statuspage what all Components are affected by this Incident
• components - This is used to Map what's the Status of a given component in the Incident

The reason for the 2 different keys - This helps show that maybe at the time of creation 5 component where affect but not all had yet experienced an outage

This becomes useful when you want to define a relationship between component 

EG - X,Y,Z are component affected but currently only Z is in Major Outage - X,Y are Partial Outage 

Getting a List of Incidents - This fetch the list of Component involved in a incident along with details regarding their Current Status and last updated and more

I hope that answered your question

[Johnson Earls]

You answered the question, but not the underlying problem, which is that the *documentation* is not sufficient.  This is one example of that.  I've reported other examples in the past.  Your API documentation is purely syntactic with no semantics whatsoever.  Please formally record this as a complaint about the lack of truly usable documentation and a request for the documentation to be improved to include things like valid values for parameters, what those parameters mean, how they're used, what results from different combinations of parameters, etc.  *SEMANTIC* information, not just syntax.

[Abhay Sarraf]

Hey @Johnson Earls 

I will share this feedback with our Internal Team to make the API documentation for understandable