Ghost Release: 2.16.0

TL;DR

Ghost 2.16.0: Admin API v2 Stable Release & UI Improvements

Ghost 2.16.0 introduces the stable version of Admin API v2 with endpoints for posts, pages, and images, along with a cleaner separation between posts and pages in the admin interface. This release also adds webhook support for post, page, and tag events, improves members security, and enhances card rendering with better caption support. The update focuses on API stability, improved developer experience, and UI refinements.

Note: The 2.16.0 NPM release zip was broken. Please use 2.16.1 instead.

Highlight of the Release

• Stable Admin API v2 endpoints for posts, pages, and images
• Separated post and page management in the admin UI
• Enhanced webhook support with post, page, and tag events
• Improved members security and authentication flow
• Better card rendering with caption support
• Serverside rendering support for members-only content

Migration Guide

API Changes

1. Uploads to Images Migration:

   • The /uploads* endpoints have been removed
   • Use the consolidated /images/upload endpoint instead
   • The response structure for /images now returns an object with a url property instead of a plain URL string
   • Theme upload field name has been renamed for consistency

2. Admin API v2 Changes:

   • Admin API keys now require kid in header
   • Default format changed from HTML to mobiledoc
   • Virtual fields like "url", "primary_tag", and "primary_author" have been stripped
   • Single author endpoints have been removed (deprecated in v0.1, removed in v2)

3. Posts and Pages Separation:

   • Posts and pages are now separate endpoints in Admin API v2
   • No longer need to send status=all parameter in Admin API v2
   • Use filter instead of status=all or data.page parameters

Webhook Consumers

• Webhook payloads now include all content formats
• Check webhook resource names for page events

Theme Developers

• New kg-card-hascaption class is available for styling cards with captions
• HTML comments now wrap card content for better format conversion

Upgrade Recommendations

Important: The 2.16.0 NPM release zip is broken. Please use version 2.16.1 instead.

This is a significant update with stable Admin API v2 endpoints and important changes to how posts and pages are managed. We recommend all users upgrade to benefit from the improved API stability, enhanced webhook support, and UI improvements.

For developers:

• Review the API changes if you're using the Admin API
• Update any code that uses the /uploads endpoints to use /images/upload instead
• If you're using Admin API keys, ensure you're including the required kid in the header

For site owners:

• Standard upgrade process applies
• No database migrations that require special attention
• Test your webhooks after upgrading to ensure they're working with the new payload format

The upgrade should be straightforward for most users, with the main considerations being for developers who are actively using the Admin API or webhook features.

Bug Fixes

Fixed Issues

• Fixed markdown text expansions sometimes resulting in sticky formatting
• Fixed Code Injection inputs not being clickable
• Fixed empty subscribers webhooks payload
• Fixed "html" being marked as changed if mobiledoc or html was not changed
• Fixed x_by being detected as changed if owner updates resources
• Fixed regression with static routes and members serverside rendering
• Fixed serialized webhook payload for deleted resources
• Fixed webhook resource name for page events

New Features

Admin API v2 Stable Release

• Stable endpoints for posts, pages, and images
• Redesigned config endpoint with improved structure
• New public /site endpoint
• Better error messages with help, code, and id fields
• Changed default format from HTML to mobiledoc
• Returns tags & authors by default
• Added computed "excerpt" field

Enhanced Webhook Support

• Added post, page, and tag related webhook trigger events
• Webhooks now include all content formats in payload
• Improved webhook debugging
• Fixed webhook payload for deleted resources

Members Improvements

• Added serverside rendering support for members-only content
• Improved members security with local token storage
• Updated members auth flow UI with dynamic settings
• Added member as global template variable for templates
• Added new member permissions for administrators

UI Improvements

• Separated post and page list screens in admin interface
• Added kg-card-hascaption class to image/gallery/embed cards with captions
• Updated mobiledoc renderer to insert HTML comments around cards for better format conversion

Security Updates

Security Improvements

• Added audience validation for content API tokens to restrict which domains can access tokens
• Updated Admin API key authentication to require kid in header according to JWT/JWS spec
• Improved members security with local token storage and 30-minute token expiry
• Removed "status" query option from Authors Content API v2 to prevent status guessing
• Removed serving of primary_tag when members is enabled

Performance Improvements

Performance Enhancements

• Improved members security and performance with local token storage
• Added hardcoded 30-minute expiry for member tokens
• Removed default debug log from base model when emitting events
• Optimized API responses by removing unnecessary virtual fields
• Improved error handling for API frame to prevent unexpected 500 errors
• Better caching with Cache-Control: private for member requests

Impact Summary

Ghost 2.16.0 represents a significant step forward in API stability and developer experience with the introduction of stable Admin API v2 endpoints. The separation of posts and pages in both the API and UI creates a cleaner, more intuitive content management experience for publishers.

The enhanced webhook system provides more granular control and better integration capabilities, while improvements to members security and authentication strengthen the platform's subscription capabilities. For theme developers, the addition of better card rendering with caption support and HTML comments for format conversion improves the flexibility of the content editing system.

This release balances developer-focused improvements with user experience enhancements, making it valuable for both technical users building on the Ghost platform and content creators using the admin interface. The API changes establish a more stable foundation for future development while maintaining backward compatibility where possible.

Note that users should skip directly to version 2.16.1 due to issues with the 2.16.0 NPM release zip.

Full Release Notes