{"_id":"56d1f33f00a2a70b00b365ed","__v":0,"project":"5526c95cf69851170038b48f","category":{"_id":"56d1f33900a2a70b00b36598","pages":["56d1f33f00a2a70b00b365e9","56d1f33f00a2a70b00b365ea","56d1f33f00a2a70b00b365eb","56d1f33f00a2a70b00b365ec","56d1f33f00a2a70b00b365ed"],"project":"5526c95cf69851170038b48f","__v":1,"version":"56d1f33700a2a70b00b3658e","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-20T16:08:19.335Z","from_sync":false,"order":7,"slug":"rest-api","title":"API"},"parentDoc":null,"user":"5564b8233b87582b003ab99b","version":{"_id":"56d1f33700a2a70b00b3658e","project":"5526c95cf69851170038b48f","__v":2,"createdAt":"2016-02-27T19:04:23.946Z","releaseDate":"2016-02-27T19:04:23.946Z","categories":["56d1f33900a2a70b00b3658f","56d1f33900a2a70b00b36590","56d1f33900a2a70b00b36591","56d1f33900a2a70b00b36592","56d1f33900a2a70b00b36593","56d1f33900a2a70b00b36594","56d1f33900a2a70b00b36595","56d1f33900a2a70b00b36596","56d1f33900a2a70b00b36597","56d1f33900a2a70b00b36598","56d1f33900a2a70b00b36599","56d1f33900a2a70b00b3659a","571f9497ada30c34003b7cee"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta","version_clean":"2.0.0-beta","version":"2.0.0-beta"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-25T16:46:51.053Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"APIs become easy to use when they follow a set of conventions. That's why we've simplified and unified as much as we can. There are exceptions to this, but for the most part the following conventions are followed by the Ionic API.\n\n## RESTful Endpoints\n\nWe do our best to make sure our endpoints are [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer). Generally, HTTP verbs denote an associated action on a resource or set of resources.\n\n* **GET** `/examples` - Fetch a collection of example resources\n* **POST** `/examples` - Create a new example resource\n* **GET** `/examples/:id` - Fetch a single example resource by its ID\n* **PATCH** `/examples/:id` - Perform a partial update of a single resource by its ID\n* **PUT** `/examples/:id` - Completely replace a single resource by its ID\n* **DELETE** `/examples/:id` - Delete a single resource by its ID\n\n## HTTP Status Codes\n\nResponses from the Ionic API return an appropriate [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for the response. You can expect successful responses to have `2xx`, user-level error responses to have `4xx`, and server-level error responses to have `5xx`. \n\nGenerally, you can expect these status codes for successful requests:\n* **GET** `/examples` or `/examples/:id` - 200 (information fetched and returned successfully)\n* **POST** `/examples` - 201 (created successfully) or 202 (queued for creation)\n* **PATCH** or **PUT** `/examples/:id` - 200 (updated successfully)\n* **DELETE** `/examples/:id` - 204 (deleted successfully, no content to return)\n\n## Structure\n\nAPI responses adhere to a common structure:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"meta\\\": {\\n    \\\"status\\\": 200,\\n    \\\"version\\\": \\\"2.0.0\\\",\\n    \\\"request_id\\\": \\\"d5ccbe45-a54e-4d19-9b58-a96c7747369f\\\"\\n  },\\n  \\\"data\\\": {\\n    ...\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n### Meta\n\nThe `meta` key is for additional information about the request, response, or API. While `meta` may contain additional fields, it will always have `request_id`, which is a generated [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) for your request, `status`, which is the same as the HTTP status code of the response, and `version`, which is the API version that was used to handle your request.\n\n### Data\n\nThe `data` key is for the actual information requested. For collections, such as **GET** `/examples`, `data` is an array. For single resources, such as **GET** `/examples/:id`, `data` is an object that is a representation of the request resource.\n\n### Error\n\nIf an error occurred, the HTTP status code will be `4xx` or `5xx`, and `data` will be **replaced** by `error`. Therefore it is imperative to check the HTTP status code (using your client library's response object or checking `status` within `meta`) before attempting to access `data`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"meta\\\": {\\n    \\\"status\\\": 400,\\n    \\\"version\\\": \\\"2.0.0\\\",\\n    \\\"request_id\\\": \\\"0005966a-185a-491b-90a8-0260ed12d9c1\\\"\\n  },\\n  \\\"error\\\": {\\n    \\\"message\\\": \\\"Authorization header is missing.\\\",\\n    \\\"link\\\": null,\\n    \\\"type\\\": \\\"Unauthorized\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nWe try to be as helpful as possible with error messages. While `error` may contain additional fields, it will always have `type`, which is a string you can use to programmatically determine the type of error, `link`, which may be null or may be a URL you can follow in our docs to further understand the error, `message`, which is a sentence or two explaining the specific error.\n\n## Pagination\n\nFor collection endpoints that support it, pagination allows you to use \"pages\" to loop through your resources. To use pagination, simply use the query param `page` with a number. The number of resources per page may differ per endpoint, but you can explicitly set the desired number with the `page_size` query param.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://api.ionic.io/examples?page=1&page_size=10\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Warning\",\n  \"body\": \"When looping through all pages, the end of results is reached when the number of resources returned is less than the `page_size`. Empty pages at the end of your results are a possibility, so be sure to handle it in your code.\"\n}\n[/block]\n## Extra Fields\n\nSome fields are not included in the default view. You can include them by using the `fields` query params. If, for example, you need to include the `foo` and `bar` fields, pass in query params like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://api.ionic.io/examples/10?fields=foo&fields=bar\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"api-conventions","type":"basic","title":"Conventions"}
APIs become easy to use when they follow a set of conventions. That's why we've simplified and unified as much as we can. There are exceptions to this, but for the most part the following conventions are followed by the Ionic API. ## RESTful Endpoints We do our best to make sure our endpoints are [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer). Generally, HTTP verbs denote an associated action on a resource or set of resources. * **GET** `/examples` - Fetch a collection of example resources * **POST** `/examples` - Create a new example resource * **GET** `/examples/:id` - Fetch a single example resource by its ID * **PATCH** `/examples/:id` - Perform a partial update of a single resource by its ID * **PUT** `/examples/:id` - Completely replace a single resource by its ID * **DELETE** `/examples/:id` - Delete a single resource by its ID ## HTTP Status Codes Responses from the Ionic API return an appropriate [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for the response. You can expect successful responses to have `2xx`, user-level error responses to have `4xx`, and server-level error responses to have `5xx`. Generally, you can expect these status codes for successful requests: * **GET** `/examples` or `/examples/:id` - 200 (information fetched and returned successfully) * **POST** `/examples` - 201 (created successfully) or 202 (queued for creation) * **PATCH** or **PUT** `/examples/:id` - 200 (updated successfully) * **DELETE** `/examples/:id` - 204 (deleted successfully, no content to return) ## Structure API responses adhere to a common structure: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"status\": 200,\n \"version\": \"2.0.0\",\n \"request_id\": \"d5ccbe45-a54e-4d19-9b58-a96c7747369f\"\n },\n \"data\": {\n ...\n }\n}", "language": "json" } ] } [/block] ### Meta The `meta` key is for additional information about the request, response, or API. While `meta` may contain additional fields, it will always have `request_id`, which is a generated [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) for your request, `status`, which is the same as the HTTP status code of the response, and `version`, which is the API version that was used to handle your request. ### Data The `data` key is for the actual information requested. For collections, such as **GET** `/examples`, `data` is an array. For single resources, such as **GET** `/examples/:id`, `data` is an object that is a representation of the request resource. ### Error If an error occurred, the HTTP status code will be `4xx` or `5xx`, and `data` will be **replaced** by `error`. Therefore it is imperative to check the HTTP status code (using your client library's response object or checking `status` within `meta`) before attempting to access `data`. [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"status\": 400,\n \"version\": \"2.0.0\",\n \"request_id\": \"0005966a-185a-491b-90a8-0260ed12d9c1\"\n },\n \"error\": {\n \"message\": \"Authorization header is missing.\",\n \"link\": null,\n \"type\": \"Unauthorized\"\n }\n}", "language": "json" } ] } [/block] We try to be as helpful as possible with error messages. While `error` may contain additional fields, it will always have `type`, which is a string you can use to programmatically determine the type of error, `link`, which may be null or may be a URL you can follow in our docs to further understand the error, `message`, which is a sentence or two explaining the specific error. ## Pagination For collection endpoints that support it, pagination allows you to use "pages" to loop through your resources. To use pagination, simply use the query param `page` with a number. The number of resources per page may differ per endpoint, but you can explicitly set the desired number with the `page_size` query param. [block:code] { "codes": [ { "code": "https://api.ionic.io/examples?page=1&page_size=10", "language": "text" } ] } [/block] [block:callout] { "type": "danger", "title": "Warning", "body": "When looping through all pages, the end of results is reached when the number of resources returned is less than the `page_size`. Empty pages at the end of your results are a possibility, so be sure to handle it in your code." } [/block] ## Extra Fields Some fields are not included in the default view. You can include them by using the `fields` query params. If, for example, you need to include the `foo` and `bar` fields, pass in query params like so: [block:code] { "codes": [ { "code": "https://api.ionic.io/examples/10?fields=foo&fields=bar", "language": "text" } ] } [/block]