The Ghost Themes Developer Hub

Welcome to the Ghost Themes developer hub. You'll find comprehensive guides and documentation to help you start working with Ghost Themes as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

ghost.url.api()

JavaScript utility for building API urls for ajax calls

Beta Feature

This recipe uses the ghost.url.api() utility, which comes from the Ghost SDK script. This is part of the Public API Beta feature and may change at any time.

From Ghost 1.0.0 the Public API is enabled by default. Once you've upgraded, it should remain fairly stable. Read more about what the Public API Beta means.

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.

Note for theme distributors

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.

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 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.

Usage

For the most part, the ghost.url.api() function follows how the same syntax as how the {{#get}} helper 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.

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 for full details on how these work.

Basic Examples

E.g. URL to fetch the last 5 published posts, including tags and author:

ghost.url.api('posts', {limit: 5, include: 'tags,author'});
<protocol>://<host>/ghost/api/<version>/posts/?limit=5&include=tags%2Cauthor&client_id=<client_id>&client_secret=<client_secret>

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:

ghost.url.api('tags', {limit: 'all', include: 'count.posts', order: 'count.posts DESC'});
<protocol>://<host>/ghost/api/<version>/tags/?limit=all&include=count.posts&order=count.posts%20DESC&client_id=<client_id>&client_secret=<client_secret>

E.g. URL to fetch 3 users who have filled out their bio and website:

ghost.url.api('users', {limit: '3', filter: 'bio:-null+website:-null'});
<protocol>://<host>/ghost/api/<version>/users/?limit=3&filter=bio%3A-null%2Bwebsite%3A-null&client_id=<client_id>&client_secret=<client_secret>

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:

ghost.url.api('posts', 'slug', mySlugVariable, {include: 'tags, author'});
<protocol>://<host>/ghost/api/<version>/users/slug/<mySlugVariable>/?client_id=<client_id>&client_secret=<client_secret>

E.g. URL for fetching a user by id, demonstrating that concatenation handles slashes:

ghost.url.api('users', '3');
ghost.url.api('users', '/3');
ghost.url.api('users', '/3/');
ghost.url.api('users/', '3/');
ghost.url.api('users/', '/3/');
<protocol>://<host>/ghost/api/<version>/users/3/?client_id=<client_id>&client_secret=<client_secret>

Examples

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:

<aside>
  <h3>Featured Posts</h3>
  <ol id="featured-posts"></ol>
</aside> 

And that the bottom of your default.hbs file looks something like this:

...
<script type="text/javascript" src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
{{ghost_foot}}
<script type="text/javascript">
 // ajax goes here...
</script>
...

Then the ajax script that goes inside those <script> tags would look something like this:

function onSuccess(data) {
  var $result = $('#featured-posts');
  $.each(data.posts, function (i, post) {
    $result.append(
      '<li>' + post.name + '</li>'
    );
  });
}  

jQuery(document).ready(function () {
  $.get(
    ghost.url.api('posts', {limit: 3, filter: 'featured:true'})
  ).done(onSuccess);
});

For more information on how to use the Ghost API, please see the API documentation.

If you have feedback, please visit the #themes channel in our slack team.

ghost.url.api()

JavaScript utility for building API urls for ajax calls