GhostContent

An Elixir client for the Ghost publishing platform's Content API.

This package allows you to use Ghost as a headless CMS in your Elixir/Phoenix project.

Full documentation of the Ghost Content API is available at: https://ghost.org/docs/content-api/

Installation

The package can be installed by adding ghost_content to your list of dependencies in mix.exs:

def deps do
  [
    {:ghost_content, "~> 0.1.0"}
  ]
end

Full documentation can be found at https://hexdocs.pm/ghost_content.

Configuration

You'll need to configure ghost_content with your Ghost Content API host and key, as follows:

config :my_app, :ghost_content,
  host: "https://my.ghost.host",
  api_key: "my-ghost-api-key

Consult the Ghost Content API documentation for more information on creating an API key.

Ghost Content Data Model

ghost_content defines three structures which mirror the core resources in the Ghost Content API:

%GhostContent.Post{}
%GhostContent.Tag{}
%GhostContent.Author{}

Note that the Ghost Content API exposes both "posts" and "pages", but that these both use the same data model, %GhostContent.Post{}.

Usage

Once configured, you can start making requests.

All API requests take a config, which is created as follows:

config = GhostContent.config(:ghost_content)

The API

Getting Posts:

GhostContent.get_posts(config)
GhostContent.get_post(config, post_id)
GhostContent.get_post_by_slug(config, slug_id)

Getting Pages:

GhostContent.get_pages(config)
GhostContent.get_page(config, page_id)
GhostContent.get_page_by_slug(config, slug_id)

Getting Authors:

GhostContent.get_authors(config)
GhostContent.get_author(config, author_id)
GhostContent.get_author_by_slug(config, slug_id)

Getting Tags:

GhostContent.get_tags(config)
GhostContent.get_tag(config, tag_id)
GhostContent.get_tag_by_slug(config, slug_id)

All API calls can be given options of include and fields to specify what exact data to return. Here are some examples, but consult the Ghost Content API documentation for accepted values for each resource type:

GhostContent.get_posts(config, include: "authors,tags")
GhostContent.get_pages(config, include: "authors,tags")
GhostContent.get_authors(config, include: "count.posts")
GhostContent.get_tags(config, include: "count.posts")

GhostContent.get_posts(config, fields: "title,url")
GhostContent.get_pages(config, fields: "title,url")

All of the calls which return multiple resources (get_posts, get_pages, get_tags, and get_authors) can take options of order, page, filter and limit. Once again, consult the official documentation for exact details on using these options with the various resources.

GhostContent.get_posts(config, limit: "all")
GhostContent.get_pages(config, limit: "15", page: 2)
GhostContent.get_pages(config, filter: "tag:elixir)
GhostContent.get_pages(config, filter: "visibility:public)

Response Format

The content API exposes two types of calls: those which return a list of resources, and those which return a single resource. They have a similar response format, except that calls returning a list include a meta map containing pagination data:

{:ok, %{meta: %{...}, posts: [...]}} = GhostContent.get_posts(config)

{:ok, %{posts: [...]}} = GhostContent.get_post(config, post_id)

# Meta-format:
%{
  pagination: %{total: 1, next: nil, prev: nil, limit: 15, pages: 1, page: 1}
}

Note that calls returning a single resource still provide the data in a list of length 1.