{"_id":"56c51f2a8dc1c51900abc142","category":{"_id":"56a96d338791090d00113bab","__v":13,"pages":["56a96d492bb3910d000ee931","56c3cec2106c12170020db96","56c51da4ba4a540d0091b9b7","56c51dc3ba4a540d0091b9b9","56c51eb916c7190d00ff7b19","56c51ec2d7b9ed19008d1752","56c51eec668eb01900719bcd","56c51effba4a540d0091b9bb","56c51f1cf7c4da0d00614b02","56c51f2a8dc1c51900abc142","56c51f367de3580d00bdaf2a","56c67b6270e7660d004a8985","56c67b7cfd00bb0d0016daad"],"project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-28T01:21:55.716Z","from_sync":false,"order":1,"slug":"patterns","title":"REST API"},"__v":2,"parentDoc":null,"version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":22,"createdAt":"2015-11-19T23:26:19.166Z","releaseDate":"2015-11-19T23:26:19.166Z","categories":["564e5a9b1560880d008d30dd","566318e1f5ca460d00f41896","56631d08cd54d50d005015fa","56631d2a81ad7417006a202c","5668ba19fbd7680d009375f4","5668cb8b10bda80d00797ed9","5668cb9d10bda80d00797eda","56830d8a3f94e00d004e2a7a","56830d9072bb720d0091f594","56830d94cb4d190d0027698e","56830dc44aecbd0d00a464c5","569e90f3c9b43e0d00c4bab1","56a96d338791090d00113bab","56b12d8336d2580d00247877","56c36bf0a869d017002ea55b","56c36bf93d30210d00ea84bb","56c77749b935671700ff0304","56c7ab9e5652c217008e091a","56cb8bdad5c6241d00ef5e61","58aefce02470660f00b54539","58aefd0bebd7370f0078b954","59ca65ca4337830026edf24f"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"user":"564e5788230d7c1700c9073e","project":"564e5930c3553e0d003e53d0","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-18T01:32:26.846Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":10,"body":"A key component of the PagerDuty REST API is the use of `references` to represent a pointer to a resource. A reference consists of five fields:\n- `id` (required, readOnly)\n- `type` (required)\n- `summary` (readOnly)\n- `self` (readOnly)\n- `html_url` (readOnly)\n\nReferences are used anywhere that the identification of an object is important, but the object itself cannot be modified. In this regard, you can think of a reference like an alias — a different object type that represents a resource. They also provide an essential subset of information about the resource that tells a client how to uniquely identify it, provides some information about what it represents, and offers locations where more information can be found about it.\n\nReferences will be used to represent relationships between resources. If a resource has a relationship with other types of entities, they may be displayed as part of the resource's schema and contain references to the resources of that type that make up the other end of the relationship. Modifying the reference or references in this field — identified only by [`id` and `type`](#section--id-and-type-) — will update the relationship between resources. Modifying any other fields of the reference has no effect on the resource it represents.\n\n##### `id` and `type`\n\nEvery PagerDuty resource can be uniquely identified by the combination of its `id` and `type`, ignoring the distinction between a given `type` and the corresponding `type_reference`. The `type` field indicates what kind of resource it is, which is [equivalent to specify its schema](doc:resource-schemas).\n\n##### `summary`\n\nThe summary field contains a string that provides a brief, human-readable summary of what this particular resource instance represents. This is server-generated and cannot be specified by the client. It should be used whenever naming a resource in a client, such as in a title, list, or link.\n\n##### `self` and `html_url`\n\nThese fields provide the full [API `show` URL](doc:endpoints#resourcesid-show) at which the resource can be accessed in full form, and the full URL at which the resource can be viewed and manipulated in the PagerDuty Web application, if applicable.\n\nIf the resource cannot be accessed directly in the API or in the Web application, one or both of these fields may be `null`.","excerpt":"","slug":"references","type":"basic","title":"Resource References"}

Resource References


A key component of the PagerDuty REST API is the use of `references` to represent a pointer to a resource. A reference consists of five fields: - `id` (required, readOnly) - `type` (required) - `summary` (readOnly) - `self` (readOnly) - `html_url` (readOnly) References are used anywhere that the identification of an object is important, but the object itself cannot be modified. In this regard, you can think of a reference like an alias — a different object type that represents a resource. They also provide an essential subset of information about the resource that tells a client how to uniquely identify it, provides some information about what it represents, and offers locations where more information can be found about it. References will be used to represent relationships between resources. If a resource has a relationship with other types of entities, they may be displayed as part of the resource's schema and contain references to the resources of that type that make up the other end of the relationship. Modifying the reference or references in this field — identified only by [`id` and `type`](#section--id-and-type-) — will update the relationship between resources. Modifying any other fields of the reference has no effect on the resource it represents. ##### `id` and `type` Every PagerDuty resource can be uniquely identified by the combination of its `id` and `type`, ignoring the distinction between a given `type` and the corresponding `type_reference`. The `type` field indicates what kind of resource it is, which is [equivalent to specify its schema](doc:resource-schemas). ##### `summary` The summary field contains a string that provides a brief, human-readable summary of what this particular resource instance represents. This is server-generated and cannot be specified by the client. It should be used whenever naming a resource in a client, such as in a title, list, or link. ##### `self` and `html_url` These fields provide the full [API `show` URL](doc:endpoints#resourcesid-show) at which the resource can be accessed in full form, and the full URL at which the resource can be viewed and manipulated in the PagerDuty Web application, if applicable. If the resource cannot be accessed directly in the API or in the Web application, one or both of these fields may be `null`.