{"category":{"version":"58810495d172b61b00d73859","project":"542fe92a5eceb608003fddc8","_id":"58810495d172b61b00d7385e","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-27T05:18:53.493Z","from_sync":false,"order":4,"slug":"tools","title":"Utilities"},"parentDoc":null,"project":"542fe92a5eceb608003fddc8","user":"542c5cfcddd3190e00228849","version":{"__v":1,"_id":"58810495d172b61b00d73859","project":"542fe92a5eceb608003fddc8","createdAt":"2017-01-19T18:25:25.206Z","releaseDate":"2017-01-19T18:25:25.206Z","categories":["58810495d172b61b00d7385a","58810495d172b61b00d7385b","58810495d172b61b00d7385c","58810495d172b61b00d7385d","58810495d172b61b00d7385e","58810495d172b61b00d7385f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.11.4","version":"0.11.4"},"_id":"58810495d172b61b00d73892","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-27T05:19:11.905Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":54,"body":"[block:html]\n{\n  \"html\": \"<div class=\\\"github-deeplinks\\\">\\n    <a href=\\\"https://github.com/TryGhost/Ghost/blob/0.10.0/core/shared/ghost-url.js\\\"><i class=\\\"fa fa-github-alt fa-right\\\"></i>Source</a>\\n    <a href=\\\"https://github.com/TryGhost/Ghost/blob/0.10.0/core/test/unit/ghost_url_spec.js\\\" class=\\\"fa fa-check-square-o fa-right\\\">Tests</a>\\n</div>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Beta Feature\",\n  \"body\": \"This function is currently a Beta feature and should be not be used in production. For more information on what Beta means, see http://support.ghost.org/public-api-beta\\n\\nTo enable this feature, visit yourblog.com/ghost/settings/labs/ and tick the 'Public API' checkbox.\"\n}\n[/block]\nUsage: `ghost.url.api('posts', {limit: 3});`\n\n### Description\n\nA JavaScript utility that makes it possible to generate the correct URL for accessing an API endpoint, without having to worry about whether the blog config has multiple domains, different protocols or a subdirectory setup. It also automatically adds the `client_id` and `client_secret` as query parameters and all query parameters are also correctly encoded. Finally, the version string in the URL is also obscured, as this approach is likely to change.\n\nIn short, it takes all of the difficulty out of building a URL and lets you focus on which endpoint you want to talk to and the specifics of your query. It is possible to build any API url you might need using this function.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"If you are building a theme to be distributed or sold, it is **critical** that you use `ghost.url.api()` to build urls for making ajax calls. Without this tool, it is not possible to create a URL which will be correct across all of the various configurations of urls, subdirectory and SSL that Ghost supports, meaning your theme would only work for some people.\",\n  \"title\": \"Note for theme distributors\"\n}\n[/block]\nThis is the first time we've made a JavaScript utility available to themes. We're planning to expand `ghost.url` to provide for building other sorts of URLs. If you have feedback on the utility in it's current form, please drop by [slack](https://ghost.org/slack/) and share :+1: \n\n## Requirements\n\nThere are 3 pre-requisites that are required in order to use this helper:\n\n1. {{ghost_head}} helper must be present in your theme.\n2. Public API access enabled in Admin-UI.\n3. You must not have disabled the `ghost-frontend` client (only accessible via the DB)\n\nThe JavaScript for this function is included via the `{{ghost_head}}` helper, only if both the Public API feature is enabled in labs and the `ghost-frontend` client is enabled. There isn't yet a UI for enabling/disabling clients but this will be added before the labs flag for Public API is removed, meaning that it is always possible to disable having this JS included in your theme should you wish.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Usage\"\n}\n[/block]\nFor the most part, the `ghost.url.api()` function follows how the same syntax as how the [{{#get}} helper](doc:get) works, in terms of arguments.\n\nThe complete documentation of the API endpoints available and the structure of the responses can be found in the [API documentation](http://api.ghost.org/v0.1/docs).\n\n## Basic Usage:\n\n> `ghost.url.api(resourceName [String], queryParams [object]);` -> URL [String]\n\n**Arguments**\n\n- `resourceName [String]` - one of **posts**, **tags** or **users**.\n- `queryParams [object]` - any of **include**, **page**, **limit**, **order**, **filter** or **fields**.\n\n**Returns**\n\n- `URL [String]` - full URL for the configured query\n\n----\n\n### Basic Arguments\n\nThe first argument you pass to `ghost.url.api` should be a string representing the resource you want to fetch / endpoint you're fetching from, so one of **posts**, **tags** or **users**. \n\nThe second argument is then an object made up of query parameters for the API, so any of **include**, **page**, **limit**, **order**, **filter** or **fields**. `ghost.url.api` ensures these are correctly encoded ready to send to the API. See the full [API parameter reference](http://api.ghost.org/v0.1/docs/parameters) for full details on how these work.\n\n### Basic Examples\n\nE.g. URL to fetch the last 5 published posts, including tags and author:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ghost.url.api('posts', {limit: 5, include: 'tags,author'});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"<protocol>://<host>/ghost/api/<version>/posts/?limit=5&include=tags%2Cauthor&client_id=<client_id>&client_secret=<client_secret>\",\n      \"language\": \"text\",\n      \"name\": \"URL\"\n    }\n  ]\n}\n[/block]\nE.g. URL to fetch all tags, including how many related posts they have, ordered so that the tag with the most posts is first:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ghost.url.api('tags', {limit: 'all', include: 'count.posts', order: 'count.posts DESC'});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"<protocol>://<host>/ghost/api/<version>/tags/?limit=all&include=count.posts&order=count.posts%20DESC&client_id=<client_id>&client_secret=<client_secret>\",\n      \"language\": \"text\",\n      \"name\": \"URL\"\n    }\n  ]\n}\n[/block]\nE.g. URL to fetch 3 users who have filled out their bio and website:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ghost.url.api('users', {limit: '3', filter: 'bio:-null+website:-null'});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"<protocol>://<host>/ghost/api/<version>/users/?limit=3&filter=bio%3A-null%2Bwebsite%3A-null&client_id=<client_id>&client_secret=<client_secret>\",\n      \"language\": \"text\",\n      \"name\": \"URL\"\n    }\n  ]\n}\n[/block]\n----\n\n##  Advanced Usage:\n\n> `ghost.url.api(pathPart [String], pathPart [String], ... queryParams [object]);` -> URL [String]\n\n**Arguments**\n- `pathPart [String]` - a string, or set of strings representing part of a url to concatenate using '/'\n- `queryParams [object]` - any of **include**, **page**, **limit**, **order**, **filter** or **fields**.\n\n**Returns**\n- `URL [String]` - full URL for the configured query\n\n----\n\n### Advanced Arguments\n\n`ghost.url.api(pathPart [String], pathPart [String], ... queryParams [object]);` -> URL [String]\n\nIf you need to build a more complex URL, this can be done by passing more path strings, and leaving the query parameter object as the last argument passed to the function.\n\nAny and all strings passed before the query parameter object will be concatenated together  into a path, such that there is only ever one `/` between each part.\n\n### Advanced Examples\n\nE.g. URL for fetching a particular post by slug:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ghost.url.api('posts', 'slug', mySlugVariable, {include: 'tags, author'});\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"<protocol>://<host>/ghost/api/<version>/users/slug/<mySlugVariable>/?client_id=<client_id>&client_secret=<client_secret>\",\n      \"language\": \"text\",\n      \"name\": \"URL\"\n    }\n  ]\n}\n[/block]\nE.g. URL for fetching a user by id, demonstrating that concatenation handles slashes:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"ghost.url.api('users', '3');\\nghost.url.api('users', '/3');\\nghost.url.api('users', '/3/');\\nghost.url.api('users/', '3/');\\nghost.url.api('users/', '/3/');\",\n      \"language\": \"javascript\"\n    },\n    {\n      \"code\": \"<protocol>://<host>/ghost/api/<version>/users/3/?client_id=<client_id>&client_secret=<client_secret>\",\n      \"language\": \"text\",\n      \"name\": \"URL\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\n### Full example showing fetching 3 featured posts using `ghost.url.api` and jQuery.ajax\n\nAssuming you have some HTML somewhere in your theme that has a space for outputting results:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<aside>\\n  <h3>Featured Posts</h3>\\n  <ol id=\\\"featured-posts\\\"></ol>\\n</aside> \",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nAnd that the bottom of your `default.hbs` file looks something like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"...\\n<script type=\\\"text/javascript\\\" src=\\\"https://code.jquery.com/jquery-1.11.3.min.js\\\"></script>\\n{{ghost_foot}}\\n<script type=\\\"text/javascript\\\">\\n // ajax goes here...\\n</script>\\n...\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThen the ajax script that goes inside those `<script>` tags would look something like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"function onSuccess(data) {\\n  var $result = $('#featured-posts');\\n  $.each(data.posts, function (i, post) {\\n    $result.append(\\n      '<li>' + post.name + '</li>'\\n    );\\n  });\\n}  \\n\\njQuery(document).ready(function () {\\n  $.get(\\n    ghost.url.api('posts', {limit: 3, filter: 'featured:true'})\\n  ).done(onSuccess);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nFor more information on how to use the Ghost API, please see the [API documentation](http://api.ghost.org/v0.1/docs).\n\nIf you have feedback, please visit the #themes channel in our [slack](https://ghost.org/slack/) team.","excerpt":"JavaScript utility for building API urls for ajax calls","slug":"ghost-url-api","type":"basic","title":"ghost.url.api()"}

ghost.url.api()

JavaScript utility for building API urls for ajax calls

[block:html] { "html": "<div class=\"github-deeplinks\">\n <a href=\"https://github.com/TryGhost/Ghost/blob/0.10.0/core/shared/ghost-url.js\"><i class=\"fa fa-github-alt fa-right\"></i>Source</a>\n <a href=\"https://github.com/TryGhost/Ghost/blob/0.10.0/core/test/unit/ghost_url_spec.js\" class=\"fa fa-check-square-o fa-right\">Tests</a>\n</div>" } [/block] [block:callout] { "type": "warning", "title": "Beta Feature", "body": "This function is currently a Beta feature and should be not be used in production. For more information on what Beta means, see http://support.ghost.org/public-api-beta\n\nTo enable this feature, visit yourblog.com/ghost/settings/labs/ and tick the 'Public API' checkbox." } [/block] Usage: `ghost.url.api('posts', {limit: 3});` ### Description A JavaScript utility that makes it possible to generate the correct URL for accessing an API endpoint, without having to worry about whether the blog config has multiple domains, different protocols or a subdirectory setup. It also automatically adds the `client_id` and `client_secret` as query parameters and all query parameters are also correctly encoded. Finally, the version string in the URL is also obscured, as this approach is likely to change. In short, it takes all of the difficulty out of building a URL and lets you focus on which endpoint you want to talk to and the specifics of your query. It is possible to build any API url you might need using this function. [block:callout] { "type": "danger", "body": "If you are building a theme to be distributed or sold, it is **critical** that you use `ghost.url.api()` to build urls for making ajax calls. Without this tool, it is not possible to create a URL which will be correct across all of the various configurations of urls, subdirectory and SSL that Ghost supports, meaning your theme would only work for some people.", "title": "Note for theme distributors" } [/block] This is the first time we've made a JavaScript utility available to themes. We're planning to expand `ghost.url` to provide for building other sorts of URLs. If you have feedback on the utility in it's current form, please drop by [slack](https://ghost.org/slack/) and share :+1: ## Requirements There are 3 pre-requisites that are required in order to use this helper: 1. {{ghost_head}} helper must be present in your theme. 2. Public API access enabled in Admin-UI. 3. You must not have disabled the `ghost-frontend` client (only accessible via the DB) The JavaScript for this function is included via the `{{ghost_head}}` helper, only if both the Public API feature is enabled in labs and the `ghost-frontend` client is enabled. There isn't yet a UI for enabling/disabling clients but this will be added before the labs flag for Public API is removed, meaning that it is always possible to disable having this JS included in your theme should you wish. [block:api-header] { "type": "basic", "title": "Usage" } [/block] For the most part, the `ghost.url.api()` function follows how the same syntax as how the [{{#get}} helper](doc:get) works, in terms of arguments. The complete documentation of the API endpoints available and the structure of the responses can be found in the [API documentation](http://api.ghost.org/v0.1/docs). ## Basic Usage: > `ghost.url.api(resourceName [String], queryParams [object]);` -> URL [String] **Arguments** - `resourceName [String]` - one of **posts**, **tags** or **users**. - `queryParams [object]` - any of **include**, **page**, **limit**, **order**, **filter** or **fields**. **Returns** - `URL [String]` - full URL for the configured query ---- ### Basic Arguments The first argument you pass to `ghost.url.api` should be a string representing the resource you want to fetch / endpoint you're fetching from, so one of **posts**, **tags** or **users**. The second argument is then an object made up of query parameters for the API, so any of **include**, **page**, **limit**, **order**, **filter** or **fields**. `ghost.url.api` ensures these are correctly encoded ready to send to the API. See the full [API parameter reference](http://api.ghost.org/v0.1/docs/parameters) for full details on how these work. ### Basic Examples E.g. URL to fetch the last 5 published posts, including tags and author: [block:code] { "codes": [ { "code": "ghost.url.api('posts', {limit: 5, include: 'tags,author'});", "language": "javascript" }, { "code": "<protocol>://<host>/ghost/api/<version>/posts/?limit=5&include=tags%2Cauthor&client_id=<client_id>&client_secret=<client_secret>", "language": "text", "name": "URL" } ] } [/block] E.g. URL to fetch all tags, including how many related posts they have, ordered so that the tag with the most posts is first: [block:code] { "codes": [ { "code": "ghost.url.api('tags', {limit: 'all', include: 'count.posts', order: 'count.posts DESC'});", "language": "javascript" }, { "code": "<protocol>://<host>/ghost/api/<version>/tags/?limit=all&include=count.posts&order=count.posts%20DESC&client_id=<client_id>&client_secret=<client_secret>", "language": "text", "name": "URL" } ] } [/block] E.g. URL to fetch 3 users who have filled out their bio and website: [block:code] { "codes": [ { "code": "ghost.url.api('users', {limit: '3', filter: 'bio:-null+website:-null'});", "language": "javascript" }, { "code": "<protocol>://<host>/ghost/api/<version>/users/?limit=3&filter=bio%3A-null%2Bwebsite%3A-null&client_id=<client_id>&client_secret=<client_secret>", "language": "text", "name": "URL" } ] } [/block] ---- ## Advanced Usage: > `ghost.url.api(pathPart [String], pathPart [String], ... queryParams [object]);` -> URL [String] **Arguments** - `pathPart [String]` - a string, or set of strings representing part of a url to concatenate using '/' - `queryParams [object]` - any of **include**, **page**, **limit**, **order**, **filter** or **fields**. **Returns** - `URL [String]` - full URL for the configured query ---- ### Advanced Arguments `ghost.url.api(pathPart [String], pathPart [String], ... queryParams [object]);` -> URL [String] If you need to build a more complex URL, this can be done by passing more path strings, and leaving the query parameter object as the last argument passed to the function. Any and all strings passed before the query parameter object will be concatenated together into a path, such that there is only ever one `/` between each part. ### Advanced Examples E.g. URL for fetching a particular post by slug: [block:code] { "codes": [ { "code": "ghost.url.api('posts', 'slug', mySlugVariable, {include: 'tags, author'});", "language": "javascript" }, { "code": "<protocol>://<host>/ghost/api/<version>/users/slug/<mySlugVariable>/?client_id=<client_id>&client_secret=<client_secret>", "language": "text", "name": "URL" } ] } [/block] E.g. URL for fetching a user by id, demonstrating that concatenation handles slashes: [block:code] { "codes": [ { "code": "ghost.url.api('users', '3');\nghost.url.api('users', '/3');\nghost.url.api('users', '/3/');\nghost.url.api('users/', '3/');\nghost.url.api('users/', '/3/');", "language": "javascript" }, { "code": "<protocol>://<host>/ghost/api/<version>/users/3/?client_id=<client_id>&client_secret=<client_secret>", "language": "text", "name": "URL" } ] } [/block] [block:api-header] { "type": "basic", "title": "Examples" } [/block] ### Full example showing fetching 3 featured posts using `ghost.url.api` and jQuery.ajax Assuming you have some HTML somewhere in your theme that has a space for outputting results: [block:code] { "codes": [ { "code": "<aside>\n <h3>Featured Posts</h3>\n <ol id=\"featured-posts\"></ol>\n</aside> ", "language": "html" } ] } [/block] And that the bottom of your `default.hbs` file looks something like this: [block:code] { "codes": [ { "code": "...\n<script type=\"text/javascript\" src=\"https://code.jquery.com/jquery-1.11.3.min.js\"></script>\n{{ghost_foot}}\n<script type=\"text/javascript\">\n // ajax goes here...\n</script>\n...", "language": "html" } ] } [/block] Then the ajax script that goes inside those `<script>` tags would look something like this: [block:code] { "codes": [ { "code": "function onSuccess(data) {\n var $result = $('#featured-posts');\n $.each(data.posts, function (i, post) {\n $result.append(\n '<li>' + post.name + '</li>'\n );\n });\n} \n\njQuery(document).ready(function () {\n $.get(\n ghost.url.api('posts', {limit: 3, filter: 'featured:true'})\n ).done(onSuccess);\n});", "language": "javascript" } ] } [/block] For more information on how to use the Ghost API, please see the [API documentation](http://api.ghost.org/v0.1/docs). If you have feedback, please visit the #themes channel in our [slack](https://ghost.org/slack/) team.