Ghost is built on top of a RESTful JSON API. This is used for all data access inside of Ghost. This feature is available since Ghost 0.7.2 and even though Ghost 1.0 was released the Public API is still in beta. But it is stable and it's used also by the Ghost Admin Panel.

API data?

The Ghost Public API provides access to all your Ghost blog's posts, tags, and users.

To activate the API (>Ghost 1.0) go to the Admin panel and click the "Labs" within the settings menu. Go to the Beta Features section and mark the Public API checkbox.

In this article we will take a look on how the Public API can be used to retrieve posts.

Basically we have two options, using handlebars or javascript/jQuery.

Here is a simple snippet to get all posts:

{{#get "posts" limit="all"}}
  {{#foreach posts}}
    // do something here
  {{/foreach}}
{{/get}}

If we want to do this in jQuery it will look like this:

$.get(ghost.url.api('posts', {limit: 'all'})).done(function (data){
  // do something with the posts
}).fail(function (err){
  console.log(err);
});

This a really simple case, most of the time we want to select posts based on some conditions, like maybe featured posts or posts with a specific tag and so on.

Fortunately the Public API has a lot of options that can help us in this matter.

Here are the available attributes we can use when retrieving posts in order get the posts that we want.

Query attributes

  • limit - Specifies maximum number of items to return ( Default is @posts_per_page defined in package.json of the theme)
  • page - The page parameter allows you to specify which page of a paginated collection to return.
  • order - The order parameter will allow to sort the data before being returned.
  • include - The include parameter adds to possibility to extend the API request, by additional related data (ex. authors, tags).
  • fields - Allows you to specify which resource fields to retrieve rather than retrieving the. whole object.
  • filter - The filter parameter allows for filtering the results returned from the various endpoints in various ways.

These attributes provide the necessary flexibility to achieve what we need. For example if we wanted to get the 3 most recent featured posts we can do it in the following way:

{{#get "posts" limit="3" filter="featured:true" order="published_at desc"}}
  {{#foreach posts}}
    // do something with the featured posts
  {{/foreach}}
{{/get}}

As you can imagine combining different attributes basically gives us endless possibilities on selecting posts that we need and creating different sections on the blog.

To achieve the same result using jQuery the code would look like this:

$.get(ghost.url.api('posts', {limit: 3, filter: "featured: true", order: "published_at desc"})).done(function (data){
  // do something with the posts
}).fail(function (err){
  console.log(err);
});

We have talked about getting posts, but we can use the Public API in a similar manner to get "tags" or "users".

What can we achieve using the API?

Well, there are a lot of use cases, just to mention a few:

  • Featured posts section
  • Latest posts section
  • Related posts
  • Users page
  • Tags page
  • and many more...

We will not go in detials in this article on how to do this, but there will be articles that will handle some of these use cases.

Tags:#ghost api#ghost theme