Public API Beta

In Ghost 0.7.2 we have added a first ‘beta’ version of API access, which gives you access to the new {{get}} helper and the embeddable ghost.url.api() helper for making ajax requests. This can be enabled via a checkbox on the labs page in your Ghost admin panel:

enable-public-api.png

This is one of the most advanced and developer-centric features we’ve ever added to Ghost, and before using it there are a few things you’ll need to know:

What does ‘Beta’ mean?

In this case, we’re using the word ‘Beta’ to indicate that this is early access to an incomplete feature. You should expect that it won’t always work correctly and that it will change in breaking ways. Essentially, we are going to make breaking changes to these features with each new release until it is is ready, so please don’t use it in production or on a blog where you care that everything works correctly.

Breaking changes will be documented, sometimes in advance of releases.

Why does API access need a ‘Beta’ phase?

The tools we’re providing for accessing the API are new and haven’t been tested by many users or theme developers. We’re using the Beta phase to collect feedback on these tools and make changes to make them as intuitive and easy to use as we can. If you try out the tools, please leave us feedback either in our slack team or email [email protected] – your feedback is very important to help us remove the ‘Beta’ label from these features.

What does the ‘Public’ in ‘Public API’ mean?

Ghost’s JSON API has the same abilities as the admin panel (in fact the admin panel uses the API) – so it will eventually be possible to read and write any data you have permissions for using the API. Some data in a blog is inherently public: your published posts, tags, and active users (minus their email and password hash). For this first release, we’re only providing access to read public data.

Additionally, for the first release, we’re only making it possible to read that data from within the theme / frontend of your blog. This is because the ‘client’ authentication that we’re providing only permits requests from internally known domains. All of this will be expanded upon in later releases where there will be a UI to create clients for different kinds of access.

How can I use the Public API features?

The first version of Public API access will give you the ability to access the API in two ways:

  1. The {{#get}} helper, documented in the theme documentation, allows you to make custom API requests to fetch extra data to display in your theme. 
  2. Using the built-in frontend ‘client’ you can make requests from your blog’s domain. This means that you can make ajax requests to the API from inside your theme. There’s an explanation of how to access the ghost api via ajax in the theme documentation.

Documentation on the structure, capabilities and responses from the API itself can be found in the api documentation.

Where can I find detailed documentation?

Please note: that the documentation for these features is being actively worked on still. Some things are not yet well documented, and the documentation may change frequently.