{"_id":"56c51eb916c7190d00ff7b19","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":21,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"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"},"parentDoc":null,"__v":10,"project":"564e5930c3553e0d003e53d0","user":"564e5788230d7c1700c9073e","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-18T01:30:33.105Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"Within each resource, several types of endpoints are provided to accomplish different tasks concering that resource.\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"/resources (index)\"\n}\n[/block]\nIndex endpoints will return a collection of the given type of resource, optionally [filtered](doc:filtering) and [sorted](doc:sorting) by parameters you provide.\n\nThe response to an index endpoint always contains a key with the plural name of the endpoint and a corresponding array of resource objects matching the query provided.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"resources\\\": [ // the actual resources are contained in this array. The endpoint producing this response would be /resources\\n\\t\\t{\\n\\t\\t\\t… // fields appear here\\n\\t\\t} // one object is in the array for each resource\\n\\t]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"index response\"\n    }\n  ]\n}\n[/block]\nEach resource object is identical to what would be returned on the equivalent [show](#resourcesid-show) endpoint.\n\nA `200 OK` response code is returned on a successful `index` request.\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"/resources/:id (show)\"\n}\n[/block]\nShow endpoints return a single resource, and may accept additional parameters to alter the presentation of fields within the resource.\n\nThe response to a show endpoint always contains a key with the singular name of the endpoint/resource and a corresponding object containing the resource's fields:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"resource\\\": { // the endpoint producing this response would be /resources/:id\\n\\t\\t… // fields appear here\\n\\t}\\n}\",\n      \"language\": \"json\",\n      \"name\": \"show response\"\n    }\n  ]\n}\n[/block]\nThe actual key name varies based on the endpoint. Consult the reference documentation for specifics.\n\nA `200 OK` response code is returned on a successful `show` request.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"/resources (create)\"\n}\n[/block]\nCreate endpoints will create a new resource according to the payload specified. They accept a body with the same format as in a `show` response, and will return a response reflecting what the created resource looks like. If properly specified, this will mirror the request body, but is likely to contain additional `readonly` fields generated by the server.\n\nIf `readOnly` fields or unrecognized fields within the resource are submitted as part of the request, they will be ignored.\n\nA `201 Created` response code is returned on a successful `create` request.\n\nA `4xx` response code is sent if something in the request was invalid, such as omitting parameters required to create the resource.\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"/resources/:id (update single)\"\n}\n[/block]\nUpdate single endpoints will modify the state of an existing resource, identified by the `id` and `type` fields within the request body. The body has the same format as would be returned from the equivalent `show` endpoint. Not all required fields for the resource must be specified; only those whose state is to be changed must be included.\n\nIf `readonly` fields or unrecognized fields within the resource are submitted as part of the request, they will be ignored.\n\nA `200 OK` response code is returned on a successful `update single` request.\n\nA `4xx` response code is sent if something in the request was invalid, such as providing an invalid value for a field within the resource.\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"/resources (update multiple)\"\n}\n[/block]\nUpdate multiple endpoints will modify the state of several resources at once, each identified by the `id` and `type` fields within the resource's body in the resource array. The request body mirrors the same format as would be returned from the equivalent `index` endpoint.\n\nEach resource specified in the array follows the same rules as would be followed in the equivalent `update single` endpoint. If any resource in the request is invalid, the entire request will be invalid and no resources will be updated.\n\nA `200 OK` response code is sent to a successful `update multiple` request.\n\nA `4xx` response code is returned if something in the request was invalid, such as providing an invalid value for a field within a given resource.\n[block:api-header]\n{\n  \"type\": \"delete\",\n  \"title\": \"/resources/:id (delete)\"\n}\n[/block]\nDelete endpoints will cause the specified resource to be removed from the account. Subsequent requests to the associated `index` endpoint will not display the resource in the response, and subsequent requests to the associated `show` endpoint will return a `404` response code.\n\nHowever, the `id` of the resource deleted, in combination with its `type`, still serve to uniquely identify the deleted resource. No resources of the same `type` will have the same `id` in the future.\n\nIn addition, deleted resources may still be referenced by other resources. In these cases, the deleted resource will always be shown as a [resource reference](doc:references) .\n\nA `204 No content` response code is returned to a successful `delete` request.\n\nA `4xx` response code is sent if it was not possible to delete the resource. The response body will contain [more specific errors](doc:errors) about why the delete request failed.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"/resources/:id/<verb> (verb)\"\n}\n[/block]\nVerb endpoints exist where an action needs to be carried out on a resource that goes beyond updating its immediate state. These endpoints will take a set of parameters unrelated to the state of the resource itself and use them as input to an action that has effects on the resource's state.\n\nThe response follows the same format as the related [`show` endpoint](#resourcesid-show), representing the resource's new state after the action has been applied.\n\nConsult the reference documentation for specifics on any verb endpoints.","excerpt":"","slug":"endpoints","type":"basic","title":"Endpoints"}
Within each resource, several types of endpoints are provided to accomplish different tasks concering that resource. [block:api-header] { "type": "get", "title": "/resources (index)" } [/block] Index endpoints will return a collection of the given type of resource, optionally [filtered](doc:filtering) and [sorted](doc:sorting) by parameters you provide. The response to an index endpoint always contains a key with the plural name of the endpoint and a corresponding array of resource objects matching the query provided. [block:code] { "codes": [ { "code": "{\n\t\"resources\": [ // the actual resources are contained in this array. The endpoint producing this response would be /resources\n\t\t{\n\t\t\t… // fields appear here\n\t\t} // one object is in the array for each resource\n\t]\n}", "language": "json", "name": "index response" } ] } [/block] Each resource object is identical to what would be returned on the equivalent [show](#resourcesid-show) endpoint. A `200 OK` response code is returned on a successful `index` request. [block:api-header] { "type": "get", "title": "/resources/:id (show)" } [/block] Show endpoints return a single resource, and may accept additional parameters to alter the presentation of fields within the resource. The response to a show endpoint always contains a key with the singular name of the endpoint/resource and a corresponding object containing the resource's fields: [block:code] { "codes": [ { "code": "{\n\t\"resource\": { // the endpoint producing this response would be /resources/:id\n\t\t… // fields appear here\n\t}\n}", "language": "json", "name": "show response" } ] } [/block] The actual key name varies based on the endpoint. Consult the reference documentation for specifics. A `200 OK` response code is returned on a successful `show` request. [block:api-header] { "type": "post", "title": "/resources (create)" } [/block] Create endpoints will create a new resource according to the payload specified. They accept a body with the same format as in a `show` response, and will return a response reflecting what the created resource looks like. If properly specified, this will mirror the request body, but is likely to contain additional `readonly` fields generated by the server. If `readOnly` fields or unrecognized fields within the resource are submitted as part of the request, they will be ignored. A `201 Created` response code is returned on a successful `create` request. A `4xx` response code is sent if something in the request was invalid, such as omitting parameters required to create the resource. [block:api-header] { "type": "put", "title": "/resources/:id (update single)" } [/block] Update single endpoints will modify the state of an existing resource, identified by the `id` and `type` fields within the request body. The body has the same format as would be returned from the equivalent `show` endpoint. Not all required fields for the resource must be specified; only those whose state is to be changed must be included. If `readonly` fields or unrecognized fields within the resource are submitted as part of the request, they will be ignored. A `200 OK` response code is returned on a successful `update single` request. A `4xx` response code is sent if something in the request was invalid, such as providing an invalid value for a field within the resource. [block:api-header] { "type": "put", "title": "/resources (update multiple)" } [/block] Update multiple endpoints will modify the state of several resources at once, each identified by the `id` and `type` fields within the resource's body in the resource array. The request body mirrors the same format as would be returned from the equivalent `index` endpoint. Each resource specified in the array follows the same rules as would be followed in the equivalent `update single` endpoint. If any resource in the request is invalid, the entire request will be invalid and no resources will be updated. A `200 OK` response code is sent to a successful `update multiple` request. A `4xx` response code is returned if something in the request was invalid, such as providing an invalid value for a field within a given resource. [block:api-header] { "type": "delete", "title": "/resources/:id (delete)" } [/block] Delete endpoints will cause the specified resource to be removed from the account. Subsequent requests to the associated `index` endpoint will not display the resource in the response, and subsequent requests to the associated `show` endpoint will return a `404` response code. However, the `id` of the resource deleted, in combination with its `type`, still serve to uniquely identify the deleted resource. No resources of the same `type` will have the same `id` in the future. In addition, deleted resources may still be referenced by other resources. In these cases, the deleted resource will always be shown as a [resource reference](doc:references) . A `204 No content` response code is returned to a successful `delete` request. A `4xx` response code is sent if it was not possible to delete the resource. The response body will contain [more specific errors](doc:errors) about why the delete request failed. [block:api-header] { "type": "post", "title": "/resources/:id/<verb> (verb)" } [/block] Verb endpoints exist where an action needs to be carried out on a resource that goes beyond updating its immediate state. These endpoints will take a set of parameters unrelated to the state of the resource itself and use them as input to an action that has effects on the resource's state. The response follows the same format as the related [`show` endpoint](#resourcesid-show), representing the resource's new state after the action has been applied. Consult the reference documentation for specifics on any verb endpoints.