Research updating some fields to use APIObject type instead of full objects

[theckman]

There are some PagerDuty REST API endpoints that return API object references instead of the full objects for specific keys, to avoid sending massive amounts of (potentially unused) JSON across the wire.

Refer to this comment on a PR where a change was required to use APIObject instead, because it was the shape expected by the PagerDuty API: #273 (comment).

The reason I think we should investigate changing this, is because per our documentation some users may expect to see a full object sent back (see #250). This would be a v2.0.0 change.

[theckman]

Another example:

go-pagerduty/webhook.go

Line 32 in e23b94c

Alerts []IncidentAlert `json:"alerts,omitempty"`

[theckman]

go-pagerduty/incident.go

Line 80 in da97010

FirstTriggerLogEntry FirstTriggerLogEntry `json:"first_trigger_log_entry,omitempty"`

go-pagerduty/incident.go

Lines 60 to 64 in da97010

	// FirstTriggerLogEntry is the first LogEntry
	type FirstTriggerLogEntry struct {
	CommonLogEntryField
	Incident APIObject `json:"incident,omitempty"`
	}

https://developer.pagerduty.com/api-reference/b3A6Mjc0ODE0MQ-get-an-incident

[theckman]

go-pagerduty/on_call.go

Lines 11 to 13 in 77a73c9

	User User `json:"user,omitempty"`
	Schedule Schedule `json:"schedule,omitempty"`
	EscalationPolicy EscalationPolicy `json:"escalation_policy,omitempty"`