@foo-software/ghost-graphql

@foo-software/ghost-graphql

GraphQL data sources, query resolvers, schemas, and types for Ghost. This project provides the pieces to power an Apollo Server. @foo-software/ghost-graphql-server package imports modules from this project to provide an Apollo Server class with pre-defined options. You should use that project for a simple, quick solution if you don't need much customization. The exports of this package could be used in a custom implentation instead of using @foo-software/ghost-graphql-server. Includes types for TypeScript support (this project is written in TypeScript as a matter of fact).

Table of Contents

• Getting Started
• TypeScript Dependencies
• Ghost Content API
  • Pagination and Filtering
  • Filter Expressions
• Custom Implementation Example
• Environment Variables
• Schema

Getting Started

Below are steps to get started with a custom implementation. If you're looking to spin up a standalone server, check out the guide here instead.

• Determine the API URL per the docs. You'll need to set this value as GHOST_URL environment variable.
• Create and retrieve your API key per the docs. You'll need to set this value as GHOST_API_KEY environment variable.
• Use the custom implementation example as a guide and / or simply peek around the code starting with the exports. You can import resolvers, data sources, etc.

TypeScript Dependencies

We use tsc to generate types and you may need to match our TypeScript version if you have build errors. Check our package.json to find our TypeScript version.

Ghost Content API

All queries fetch from Ghost's Content API.

Pagination and Filtering

Resolvers with pagination and filter arguments can be found by inspecting the schema. Arguments mirror the parameters as documented.

Resources with pagination respond with a list of edges loosely based on the GraphQL connection spec provided by Relay. Pagination does not support cursors for the time being due to limitations from Ghost's Content API.

Filter Expressions

Filtering has evolved a bit in this project. We initially provided a filter argument which is an array of string type ([String]), however this led to unintuitive behavior as described in issue #8. Typing it in this way was naive in that it adds an or operator with multiple filters like filter: ["feature:true", "tag:some-tag"].

In order to leverage the full power of Ghost's filter expression syntax, it's best to now use the filterExpression argument (String type) instead of the original filter argument.

For example, if I wanted to fetch all feature posts and exclude tags with some-tag, I would use filterExpression like so:

filterExpression: "featured:true+tag:-some-tag"

Note the use of the and operator (+) and negation operator (-).

Custom Implementation Example

In most custom implementations, you'll only need to import resolvers. For implementations that are more complicated - it is possible to import any part of this package, including data sources, types, etc - just take a look at what is exported.

Before following the example below, make sure you've setup environment variables per the getting started guide.

Example

Example assuming you've setup a server similar to the example found in Apollo Server docs.

import {
  authorResolver as author,
  AuthorsDataSource,
  authorsResolver as authors,
  pageResolver as page,
  pagesResolver as pages,
  PagesDataSource,
  postResolver as post,
  postsResolver as posts,
  PostsDataSource,
  settingsResolver as settings,
  SettingsDataSource,
  tagResolver as tag,
  TagsDataSource,
  tagsResolver as tags,
} from '@foo-software/ghost-graphql';

const server = new ApolloServer({
  resolvers: {
    Query: {
      author,
      authors,
      page,
      pages,
      post,
      posts,
      settings,
      tag,
      tags,
    },
  },
  dataSources: () => {
    return {
      authorsDataSource: new AuthorsDataSource(),
      pagesDataSource: new PagesDataSource(),
      postsDataSource: new PostsDataSource(),
      settingsDataSource: new SettingsDataSource(),
      tagsDataSource: new TagsDataSource(),
    };
  },
  context: () => {
    return {
      token: 'foo',
    };
  },
});

Environment Variables

Name	Description	Type	Required	Default
GHOST_API_KEY	A Ghost Content API key as documented here.	string	yes	--
GHOST_API_VERSION	The version of Ghost API as documented here.	enum { v3 = 'v3' }(only support for v3 at this time)	no	v3
GHOST_URL	A Ghost admin URL as documented here. Don't use a trailing slash.	string	yes	--

Schema

The schema structure can be seen in schema.graphql of the @foo-software/ghost-graphql package.